﻿
 User Interface Reference
------------------------------------------------------------------------

The below is not intended to be an exhaustive list of keyboard inputs,
although it comes pretty close.

Key combinations marked as "alternate" typically aren't listed
in the menus and are more likely to be replaced or removed
in the future if need be. "Pseudo combinations" mean that the
qualifier key is unnecessary and ignored, but the combination
is still listed since most people are used to typing, for example,
Control-C for copy operations.

Many of these require the pop-up-style-windows option to be enabled
(which is now the default). It can be found under the Misc tab in
the options dialog (accessible by pressing Alt-O).

Some shortcuts will only work while emulation is halted. In most cases
this is done to avoid sending unwanted keystrokes to the virtual X68000.

Combinations utilizing the Alt key were heavily used because the X68000
lacks that particular key. To invoke combinations involving the Alt key,
press the Alt key first to avoid sending extraneous input to the X68000.
For example, you should always press Alt-Shift-K instead of Shift-Alt-K.
Otherwise the VM will detect the Shift key being depressed.

The Number Pad (not present on all keyboards) may function differently
depending on the state of the Number Lock (NumLock) and/or if either
Shift key is depressed. If it is behaving unexpectedly, try using the
equivalent keys found elsewhere on the keyboard, or toggle NumLock.

Speaking of Number Lock, if it refuses to toggle, press Alt-NumLock instead.
(This is unnecessary during menus/dialogs or when a subwindow is active.)
The reason the lock state remains the same when pressing NumLock is because
that key is located in the same position as the X68000 CLR key would be;
you wouldn't want the LED changing state every time you press CLR.



 Menu Interface

If a menu has too many items to display all at once, the menu
will have scroll controls on the top and bottom. You can click
them to scroll the menu, but it is much more efficient to use
the Page Up and Page Down keys to scroll entire pages at a time.
The algorithm attempts to move the current item off the viewable
region by one unit so that new pages will have entirely different
contents without skipping any items.

Holding the Delete key while selecting an item from an MRU menu
(the history of used files) will remove that item from the menu.
They will also be removed if the referenced file no longer exists.
The same principle applies to the cheat menu interface and the
little-used Window menu, as well as the file system browser.

Holding F2 while selecting an item from an MRU menu or the file
browser will give you the opportunity to rename the underlying file.
Renaming files this way ensures that XM6 is aware of the changes.
The extension, if any, cannot be changed.

Holding Control while selecting an item from the cheats menu
will open the dialog used to edit the selected cheat. F2 will
do the same, except the cheat name will have focus initially.
When applied to vectors, Control sets a breakpoint at the address.
Control also closes specific windows listed under the Window menu.

Holding Shift while selecting an item from a floppy disk MRU menu
will cause the disk image to be inserted into the other drive.
Holding Control will insert the disk image into both drives.

Please be aware that holding Shift while activating an MRU keyboard
mnemonic might not work in certain situations, such as when using
the Number Pad. Shift-clicking will always work, however.

Be aware that not all Shift/Control combinations are documented.

Most menu items have associated mnemonic keys, although your OS
may be hiding them, particularly if you opened the menu using
the mouse. A few uncommonly used menu items may have a hidden
mnemonic of Tab, although this feature takes advantage of
undocumented behavior and therefore might not work on certain
systems - you can test it on the Tools menu if you are curious.

Due to being "invisible", the policy regarding the Tab mnemonic
is that it should never activate any commands; therefore it is
always safe to try it. It may cycle through several items on the
same submenu, so you can try pressing it again if there is yet
another item you are trying to reach.

If the menu bar is present (which is the default except when in
full-screen mode) one can access it via keyboard by pressing Alt
or F10, unless they are mapped to X68000 keys, either explicitly
by the user or indirectly, as in Game Mode.



 General Shortcuts and Accelerators

Alt		Open the active window's menu (system hotkey) (unless mapped)
Alt, Space	Open system menu of active window (system hotkey)
Alt, 0		Access the Floppy Drive 0 menu
Alt, 1		Access the Floppy Drive 1 menu
Alt, 2		Access the Floppy Drive 2 menu (pop-up version)
Alt, 3		Access the Floppy Drive 3 menu (pop-up version)
Alt, C		Access the CD-ROM menu
Alt, D		Access the Debug menu
Alt, F		Access the File menu
Alt, H		Access the Help menu
Alt, M		Access the Magneto-Optical Drive menu
Alt, T		Access the Tools menu
Alt, V		Access the View menu
Alt, W		Access the Window menu

 The active window must have a caption and/or menu bar for the above to work.
 Another requirement is that neither Alt key can be mapped (unless emulation
 is paused). If unmapped, F10 can be used in place of Alt for all of the above.
 You can still use the accelerators below to access menus even if Alt is mapped.

Alt-0		Access the Floppy Drive 0 menu (*)
Alt-1		Access the Floppy Drive 1 menu (*)
Alt-2		Access the Floppy Drive 2 menu (pop-up version) (*)
Alt-3		Access the Floppy Drive 3 menu (pop-up version) (*)
Alt-A		Save state file as...
Alt-Shift-A	Save state file as... (won't disturb the active state file path)
Alt-B		Break / Execute (Pause / Unpause) (alternate)
Alt-C		Access the CD-ROM menu
Alt-D		Access the Debug menu
Alt-E		Eject disk (Drive 0)
Alt-Shift-E	Eject disk (Drive 1)
Alt-Ctrl-E	Eject disk (all floppy drives)
Alt-F		Access the File menu
Alt-G		Toggle Game Mode (i.e. uses an alternate keyboard mapping)
Alt-Shift-G	Toggle Game Mode (with a few differences in the mapping)
Alt-H		Access the Help menu
Alt-I		(Re)insert most recent disk and advance media (Drive 0)
Alt-Shift-I	(Re)insert most recent disk and advance media (Drive 1)
Alt-Ctrl-I	(Re)insert most recent disk (Drive 0 and Drive 1)
Alt-J		Toggle keyboard controller emulation
Alt-K		Open/Close Software Keyboard
Alt-Shift-K	Open/Close Software Keyboard and relocate it
Alt-L		Load most recent state file
Alt-Shift-L	Load second most recent state file
Alt-Ctrl-L	Load a state file through a dialog
Alt-M		Access the Magneto-Optical Drive menu
Alt-N		Like Alt-F11 except it will hide/unhide instead of closing
Alt-Shift-N	Alternate for Alt-F11
Alt-O		Options (only the mostly frequently needed pages)
Alt-Shift-O	Options (all pages)
Alt-P		Toggle high-priority mode
Alt-Q		Quick Screen Shot (sequentially numbered)
Alt-Shift-Q	Screen Shot to clipboard
Alt-R		Reset emulation
Alt-Shift-R	Reset emulation and clear memory
Alt-Shift-S	Save state to the currently active state file
Alt-S		Save state to a sequentially numbered file (quick save)
Alt-T		Access the Tools menu
Alt-U		(unused)
Alt-V		Access the View menu
Alt-W		Access the Window menu
Alt-X		Exit program
Alt-Y		Dynamic Memory Search
Alt-Z		(unused)

 * Won't work when using the Number Pad keys even if Number Lock is active.

 The shortcuts listed above which access a menu are usually still available
 when a pop-up window is active or the menu bar is hidden (as when full-screen),
 although you may get the pop-up version of the menu in the latter case.

 The qualifier "halted" means the virtual X68000 is paused or turned off.
 Similarly, "running" means the VM is not halted. Certain key combinations
 are only available in one state or the other, or have differing effects.

F1		Open this reference file (when halted)
F5		Execute (when halted) (alternate)
F6		Same function as Tab (see below) (when halted)
F9		Toggle breakpoint (a disassembly window must be open)
F10		Open the active window's menu (system hotkey) (when running) (*)
F10		Meta key (alternate) (unless mapped) (when running)
F10		Step over the next instruction (when halted)
F11		Mapped to the X68000 F10 key by default (when running)
F11		Execute the next instruction (when halted)
F12		Toggle Mouse Mode (alternative to MMB) (when running) (*)
F12		Skip ahead (when halted)
Ctrl-F5		Run with all breakpoints set to the disabled state (when halted)
Ctrl-F9		Set a one-shot breakpoint (a disassembly window must be open)
Ctrl-F10	Run to cursor (a disassembly window must be open)
Ctrl-F11	Run to end of subroutine (when halted)
Ctrl-F12	(reserved) (when halted)
Shift-F9	Toggle the enable state of a breakpoint / create a disabled BP
Shift-F10	Open the pop-up menu (if any) of active window (when running)
Shift-F10	Run to next instruction (when halted)
Shift-F11	Step out (when halted)
Shift-F12	Execute the next instruction (when halted) (alternate)
Ctrl-Shift-F10	Same as Shift-F10 (open pop-up menu) but also works while halted
Alt-F1		Open this reference file
Alt-F4		Close the active window or exit the program (system hotkey)
Alt-F5		Save temporary state file (kept in RAM; lost when program exits)
Alt-F6		System hotkey to switch between two windows (NT 5.2 and earlier)
Alt-F8		Load temporary state file
Alt-F9		Specify breakpoint to add/remove (includes clipboard preloading)
Alt-Ctrl-F9	Same as Alt-F9 except one-shot
Alt-Shift-F9	Same as Alt-F9 except one-shot (alternate)
Alt-F11		View -> Processor -> All
Alt-F12		Break / Execute (Pause / Unpause)
Alt-Pause/Break	Pause / Unpause (Break / Execute)
Alt-Backspace	Cycle through sequentially numbered state files (backwards)
Alt-Shift-Bkspc	Cycle through sequentially numbered state files (forwards)
Alt-NumLock	Toggle the keyboard's LED without sending a key-press to the VM
Alt-CapsLock	Toggle the keyboard's LED without sending a key-press to the VM
Alt-Insert	Send clipboard text to the VM through the emulated keyboard
Alt-SysRq	Copy active window's entire bitmap to clipboard (system hotkey)
SysRq / PrtScr	Copy entire screen to the clipboard (system hotkey) (**)
Scroll Lock	Toggle an LED on your keyboard (no function in XM6) (**)
Number Lock	Mapped to the X68000 CLR key by default (Alt-NumLock to bypass)
Numpad 0 / Ins	Frame Advance (when halted)
Pause/Break	Unpause (Execute) (when halted)
Left  Shift	Mapped to the X68000 SHIFT key by default
Right Shift	Mapped to the X68000 SHIFT key by default (hidden mapping)
Left  Control	Mapped to the X68000  CTRL key by default
Right Control	User-defined X68000 key, or interpreted as the X68000 CTRL key

* Intended to be a user-defined X68000 key. The listed functionality remains
  active for backwards compatibility and will be disabled if the key is mapped.

** Can be configured as a user-defined X68000 key, but this is not recommended.

Alt-PageDown	Cycle through windows
Alt-PageUp	Cycle through windows in reverse order
Tab		Cycle through windows (when halted)
Shift-Tab	Cycle through windows (when halted, reverse order)
Ctrl-Tab	Activate frame window (when halted)
Ctrl-PageDown	Cycle through windows (when halted, skips frame window)
Ctrl-PageUp	Cycle through windows (when halted, skips frame window, reverse)
Ctrl-ESC	System hotkey
Ctrl-Shift-ESC	System hotkey

 Many of the "when halted" shortcuts above also effectively work while the VM
 is running if a subwindow is currently active. See "General Subwindows" below.

Application	Meta key (unless mapped) (refer to the documentation later on)
Application	Open pop-up menu of active window (system hotkey) (a.k.a Apps)
Apps, Space	Open system menu for frame window
Alt-Space	Open system menu of active window (system hotkey)
Alt-Enter	Toggle full-screen mode
Grave (`)	Toggle speed limiting (same key as Tilde) (running) (*)
Grave (`)	Toggle speed limiting (same key as Tilde) (halted)
Shift-Grave (~)	Toggle MPU unlimited-speed mode (running) (*)
Shift-Grave (~)	Toggle MPU unlimited-speed mode (halted)

* Behaves as a momentary or toggle depending on how long the key is pressed.
  The functionality will be disabled if the key is mapped by the user.

Mouse Wheel	Change stretch settings / mode (frame window must be active) (*)
Middle Button	Toggle Mouse Mode (when running) (**)
Middle Button	(unassigned) (when halted)

 * Effects vary considerably. See the section "Options Reference (Graphics)".
** This feature can be disabled in the Mouse tab of the Options dialog.

Ctrl-Alt-X may launch XM6, or bring it to the foreground, if you installed
the desktop shortcut (see Tools > Install or consult the read-me file).



 General Subwindows (only applies to active, pop-up style windows)

C		Copy text/bitmap to clipboard (only certain window classes)
Ctrl-C		Copy text/bitmap to clipboard (pseudo combination)

F1		Open this reference file
F4		Close window
Alt-F4		Close window (pseudo combination) (system hotkey)
Ctrl-F4		Close all windows
Shift-F4	Close all windows except the active window
F12		Toggle Mouse Mode (unless the key is mapped) (when running)

Ctrl-PageDown	Cycle through windows (*)
Ctrl-PageUp	Cycle through windows in reverse order (*)
F6 / Tab	Cycle through windows (*)
Shift-F6/Tab	Cycle through windows in reverse order (*)
Ctrl-F6/Tab	Activate frame window

Pause/Break	Toggle VM execution state
Grave (`)	Toggle speed limiting (same key as Tilde)
Shift-Grave (~)	Toggle MPU unlimited-speed mode

 * Skips the frame window when emulation is running, for usability reasons.

 Shortcuts to access the menu bar (e.g. Alt-T) are also usually available.

 Certain window types have their own commands that take priority over the above.
 A few windows, and most dialogs, do not support any special keyboard commands.
 Many of the above commands will be masked by accelerators when halted.



 Scrollable Bitmap Subwindows (see also General Subwindows)

Up/Down		Scroll by pixels   (vertically; hold Ctrl and/or Shift for more)
Left/Right	Scroll by pixels (horizontally; hold Ctrl and/or Shift for more)
Ctrl-Up/Down	Scroll by several pixels (vertically)
Ctrl-Left/Right	Scroll by several pixels (horizontally)
Page Up/Down	Scroll by the window size (vertically)
Shift-PgUp/Down	Scroll by the window size (horizontally)
Home/End	Scroll to the limits (vertically)
Shift-Home/End	Scroll to the limits (horizontally)
Alt-Space, X	Maximize window (not applicable to some windows)



 General Menus

Home		Move to the first item in the menu
End		Move to the final item in the menu
Up		Move to the preceding item
Page Up		Move to the preceding page (or top if the menu is fully visible)
Down		Move to the following item
Page Down	Move to the following page (or end if the menu is fully visible)
Right / Left	Open / close submenus or switch to a different top-level menu

 Your system may temporarily override Number Lock while Shift is depressed.

Escape		Close current submenu or deactivate caption/menu bar
Alt		End menu processing entirely
F10		End menu processing entirely (after releasing the key)
Application	End menu processing entirely (after releasing the key)

Enter / Return	Select the current item and close the menu, or open a submenu
F2		Hold while selecting an item to rename the underlying file
Delete		Hold while selecting an item to remove the item / delete file
Shift		May change the interpretation of a selected item if held (*)
Control		May change the interpretation of a selected item if held (*)

 You may press the key corresponding to any underlined letter/number/symbol
 (the "mnemonic" or "shortcut") to directly select an item, even if it is
 not currently underlined (due to opening a menu via the mouse, for example).

 If you press a key without a corresponding mnemonic for the current (sub)menu,
 then the system will attempt to match it with the next menu item found that
 begins with the corresponding character, wrapping around if necessary.

 If there are multiple matches when you press a key, the next matching item
 will become highlighted but the menu will not close. (Try pressing Enter.)

 * See the Menu Interface section earlier for some examples.



 Options Dialog

Ctrl-PgUp/PgDwn	Switch to the next / previous tab
Enter / Return	Apply any changes made on every tab and close the dialog
Escape		Cancel all changes



 RTC Window (keyboard inputs require the pop-up style setting)

Y	Change the year
M	Change the month
D	Change the day
H	Change the hour
N	Change the minute
S	Change the second

You can also double-click certain fields with the left mouse button.



 Disassembly Window (most of these require active, pop-up windows)

A		Copy current address to clipboard
B		Cycle through breakpoints in numerical order
C		Copy disassembly to clipboard
Ctrl-C		Copy disassembly to clipboard (pseudo combination)
Shift-C		Copy disassembly to clipboard (one-line only)
G		Go to an address
Ctrl-J		Set 68000 PC to top line of disassembly
M		Go to the address taken from the first memory window found
Shift-M		Relay the current address to the first memory window found
O		Toggle one-shot breakpoint on current line
P		Shift disassembly view to current PC
Ctrl-V		Go to the address stored on the clipboard (with some filtering)
Ctrl-Z		Undo/redo the previous code patch

Delete		Edit or replace instruction on current line

Enter		Step over next instruction (alternate)
Ctrl-Enter	Run to cursor (alternate)
Shift-Enter	Run to next instruction (alternate)
Plus (numpad)	Execute next instruction (alternate)
Ctrl-Plus	Run to end of subroutine (alternate)
Shift-Plus	Step out (alternate)
Minus (numpad)	Step out (alternate)
Asterisk (pad)	Run to cursor (alternate)
Right/Alt-Right	Navigate to the address of the operand on the top line
Shift-Right	Navigate to the address of the second operand on the top line
2, Right	Navigate to the address of the second operand (alternate)
Left/Alt-Left	Go back (uses an internal address stack)

Up/Down		Scroll by lines
Ctrl-Up/Down	Scroll by words (*) (Shift or Ctrl-Shift will also work)
Page Up/Down	Scroll by pages
Space/Backspace	Scroll by pages
Home/End	Jump to top/bottom; if already there, go to next/prev section

Mouse Wheel	Scroll by lines
Ctrl-Wheel	Scroll by pages
Shift-Wheel	Scroll by pages (alternate)
Ctrl-Shift-Whl	Scroll by words (*)

 * I.e. two bytes in memory. Helpful in troublesome situations
 such as instructions getting masked by preceding garbage.

RMB		Open context menu
 Follow Operand	Jump to operand on line which was right-clicked
 Jump to Cursor	Set PC to mouse-selected line

LMB		Set / Remove Breakpoint
Shift-LMB	Enable / Disable Breakpoint (*)
Ctrl-LMB	Set a One-Shot Breakpoint
Ctrl-Shift-LMB	Run to Cursor (**)

 * If no breakpoint is present, a disabled breakpoint will be created.

 ** This works by setting/moving a special one-shot breakpoint (#9)
 that is reserved exclusively for this sort of purpose.



 Breakpoints Window (keyboard inputs require the pop-up style setting)

n        [1-8]	Toggle breakpoint n
Shift-n		Delete breakpoint n
A		Copy address of upper breakpoint to the clipboard
Shift-A		Copy address of lower breakpoint to the clipboard
Ctrl-C		Copy all addresses to the clipboard
Ctrl-V		Set one or more breakpoints using addresses from the clipboard
E / Enter	Enter a breakpoint address manually
Delete		Delete one breakpoint (from the top)
Backspace	Delete one breakpoint (from the bottom)
Shift-Delete	Delete all breakpoints
Shift-Backspace	Delete all breakpoints

Double LMB	Toggle one breakpoint
 with Ctrl	Toggle all breakpoints
 with Shift	Change breakpoint address

Note that a breakpoint matching the current PC will be highlighted.



 MPU Registers Window (keyboard inputs require the pop-up style setting)

n        [0-7]	Modify register Dn
Shift-n		Modify register An
P		Modify the Program Counter
S		Modify the Status Register
Ctrl-n		Copy the value of register Dn to the clipboard
Ctrl-Shift-n	Copy the value of register An to the clipboard
Ctrl-P		Copy the value of the Program Counter to the clipboard
Ctrl-S		Copy the value of the Status Register to the clipboard



 Memory Window (most of these require active, pop-up windows)

A		Copy current address to clipboard
F		Open search dialog
G		Go to address
M		Toggle Dynamic Memory Search

B		Change display units (byte)
L		Change display units (long)
W		Change display units (word)

Ctrl-V		Go to the address taken from the clipboard
D		Go to the address taken from the first disassembly window found
Shift-D		Relay the current address to the first disassembly window found

n        [0-7]	Go to the address contained in register An
Shift-n  [0-7]	Go to the address contained in register Dn
P		Go to the address contained in the Program Counter

F3		Repeat last search
Shift-F3	Repeat last search (backwards)

Left/Right	Navigate through the memory window view history
Up/Down		Scroll by lines
Page Up/Down	Scroll by pages
Space/Backspace	Scroll by pages
Home/End	Jump to top/bottom

Mouse Wheel	Scroll by lines
Ctrl-Wheel	Scroll by pages
Shift-Wheel	Scroll by pages (alternate)
Ctrl-Shift-Whl	Jump to top/bottom

Enter		Edit selected value

Double LMB	Edit memory value (also useful for copying values)
 with Ctrl	Jump to address stored in memory location
 with Shift	Shift the selected address by two  (only for "long" units)
 with Shift	Treat the selected value as 32-bit (only for "word" units)

Shift and Control also modify the behavior of the Enter key in a similar way.



 Search Dialog

Escape / Alt-F4	Close the window
Control		Close the window after searching (while activating a search)
Shift		Reverse the search direction (while activating a search)



 Dynamic Memory Search (DMS)

Most of the keys used by the Memory Window apply in this mode as well.
Keys in parentheses are unofficial and may potentially be reassigned!
The '^' symbol means Control must be held down. "Dbl" means double click.

#	Set default input radix to 10 (i.e. input is interpreted as     decimal)
$	Set default input radix to 16 (i.e. input is interpreted as hexadecimal)
^C	Copy addresses (within reason) to the clipboard
^V	Add any addresses found on the clipboard
H ?	View integrated help for the DMS feature
M (Q)	Toggle Dynamic Memory Search (i.e. switch between DMS and normal mode)
R	Toggle the run-after-search feature
V (5)	Toggle viewing mode between compact and full
^T	Toggle the search region between RAM and TVRAM
U	Update RAM copy (previous values)
^U	Toggle automatic update of RAM copy after relative searches
X	Switch default input radix between 10 and 16
Z	Undo (only one level saved) (twice to redo) (doesn't update RAM copy)
F1	Open reference manual
F3	Repeat previous search
Space	Repeat previous search
Backspc	Start a new search
Enter	Modify the value stored at the current line
^Enter	Add a cheat using the address on the current line
Dbl-LMB	Modify the value stored at the targeted address
^DblLMB	Add a cheat using the targeted address


Compared to the previous state:

I	Increased (numpad '/' is an alternate)
D	Decreased
+	Incremented
-	Decremented
Y	Changed by... (specified delta can be either positive or negative)
Shift-Y	Changed by... (checks for both positive and negative deltas)
C (*)	Changed
S	Same


Compared to a specific value:

0 (P)	Signed > 0   Remove zeros and negative values (values with sign bit set)
E =	Equal
  ! (N)	Not equal (not very useful beyond a few common values like 0 or FF)
 < >	Unsigned inequality (except for zero in which case it will be signed)
	 Use Control for <= and => and Alt for signed (and Shift is optional)


The following directly constrain the addresses being observed:

[ ]	Inclusive address range (hold Shift and/or Control for exclusive)
( )	Exclusive address range
 @	View only one specified address (clears all then restores one address)
 &	Restore a previously removed address

Delete	Remove top address
Ctr-Del	Remove an arbitrary address
Shf-Del	Remove all addresses from current line onward (not Num Lock compatible)
Alt-Del	Remove all addresses
Shf-BS	Remove all addresses prior to the current line



 Useful Combos

Alt-T, U	Toggle audio muting
Alt-F, 1	Load most recent state file (Alt-L also works)
Alt-F, S	Save to current state file (Alt-Shift-S also works)


 Useful Combos - Disassembly Window

G, Enter	Add current line to address history
Right, A, Left	Copy destination address of current instruction


 Remember: If there isn't an accelerator for a shortcut you'd like,
 you can usually get the same effect with a few extra keystrokes by
 using the Alt or Apps key to access a menu and then pressing the key
 corresponding to the command you want (the key should be underlined.)




Meta Key:

The Meta key is a unique feature of XM6 Pro-68k. Its purpose is to enable
the user to press all the special X68000 keys unavailable on modern English
keyboards without switching input modes or other cumbersome methods. It acts
like a special kind of qualifier key (such as Shift or Control); while it is
depressed, other keys may be interpreted differently.

There are two meta keys available at this time: F10 and Apps (or Application).
Both of these keys are system hotkeys and they are not part of the default
keyboard mapping. As long as they have not been mapped to an X68000 key,
they will function as a meta key while retaining their functionality as
system hotkeys: if they are pressed and released with no intervening keys
being depressed then they function as normal; if a second key is depressed
at any point prior to being released, they function as a meta key.

As an aside, part of the reason those two keys were chosen is because their
system-hotkey functionality only triggers when they are released, allowing
them to be multiplexed as meta keys with no loss of functionality. This does
mean that if you press a meta key but release it without following through
by pressing any other key, you might instead receive the key's system-hotkey
functionality, such as opening a context menu, which can be a mild annoyance
if unexpected.

While a meta key is depressed, other keys are subject to translation, as shown
in the table below. Any key without a translation will function as normal.

For example, to press HELP (which sometimes changes the screen mode in games),
hold down a meta key and then press F9 or '-' on the numerical pad. To hold
down Touroku while a game is booting (which might enable MIDI, for example)
depress a meta key and either F7 or '*' on the num-pad, then keep them held
until you are sure that the game has detected them.

With a small amount of memorization, you can use this feature to press any
X68000 key at any time, assuming you haven't changed the default keyboard
mapping too much, and also assuming that you have a "complete" English
keyboard - laptops or condensed keyboards may not have all the needed keys.

If you are unwilling to refer to the table below, you can always open the
Software Keyboard window (Alt-K) and hover the mouse over specific keys.
With a few exceptions, if there is a meta-key combination, it will be shown
in the status bar. It is a good idea to also use the Software Keyboard if
attempting multiple simultaneous meta-key translations, due to a limitation
described below. (Multiple keys are rarely needed; XF1+G would be an example.)

This mode has priority over Controller Mode, so if you need to press the 'S'
key (for example) while Controller Mode is active, Meta-S would do the trick,
assuming you did not remap the S key to something else. (Controller Mode
is another input mode that maps keys to virtual controller buttons/axes;
it temporarily remaps the A,S,D,Z,X,C keys, among others.)

Meta-Key Limitations:

One limitation of this feature is that you may not be able to press as many
keys simultaneously. Most keyboards effectively restrict certain groups of
keys from being pressed in ways that can seem very arbitrary. Probably all
keyboards can accept any two keys at the same time, but three or more might
not work, and this can be difficult to predict.

Therefore, when using a meta key, you're already at the reliable limit of two
keys the moment you press another key. This is not likely to be a problem in
practice, but you should be aware of the possibility. If you do need to press
a number of exotic keys simultaneously, the most reliable way is to open the
Software Keyboard window and right-click each key individually.

Another method is to try using a different meta key - the limitations will
likely be different. And if you have multiple keyboards connected, pressing
a meta key on one will not impose any additional limitations on the others.
Finally, Game Mode could be used as an alternative, although the key mappings
are very different.

For example, on my keyboard, I can press all of U I O P simultaneously unless
Apps is also depressed (F10 works, however). As another example, my keyboard
only allows one of * and - on the numerical pad when combined with Apps, but
both can be simultaneously depressed when combined with F10.

Pressing multiple keys that translate to the same X68000 key will work,
but you may find that the VM key will be released as soon as any of the
keys are released, even though others are still depressed. This is not
likely to be a problem unless you don't realize what you are doing.
Remember that you can always open the Software Keyboard window to help
you understand which inputs the X68000 is actually receiving.

This feature is not available when the keyboard is in Game Mode, but you may
not need that mode at all if you are conversant with the meta key.

The other set of key translations, which are used to aid typing on English
keyboards, will also be unavailable while a meta key is depressed, in order
to keep the translated keyboard pure. This is not likely to matter at all.


Key		Translation	Explanation
---		-----------	------------------------------------------------
Control (L/R)	CTRL		In case you mapped these keys to something else
 Shift  (L/R)	SHIFT		In case you mapped these keys to something else

Pause/Break	COPY		Mnemonic (COPY tends to _break_ X68000 software)

F1		XF1		Mnemonic
F2		XF2		Mnemonic
F3		XF3		Mnemonic
F4		XF4		Mnemonic
F5		XF5		Mnemonic
F6		Kigou Nyuuryoku	Arbitrary (記号入力)
F7		Touroku		Arbitrary (登録)
F8		HELP		Arbitrary
F9		CLR		Arbitrary
F10		F10		Mnemonic (F10 can also be used as a meta key)
F11		OPT.1		Mnemonic
F12		OPT.2		Mnemonic

Delete		OPT.1		Location
End		OPT.2		Location
Page Up		ROLL UP		Semantics
Page Down	ROLL DOWN	Semantics

/ (num-pad)	Kigou Nyuuryoku	Location (記号入力)
* (num-pad)	Touroku		Location (登録)
- (num-pad)	HELP		Location


	LED toggle keys

H		Hiragana	Mnemonic (ひらがな) (requires Zenkaku and Kana)
Z or F		Zenkaku		Mnemonic (全角) ('F' for "Full Width")
K		Kana		Mnemonic (かな)
R		Romaji		Mnemonic (ローマ字)
C		Code Nyuuryoku	Mnemonic (コード入力)


	Ten-key-pad keys that are unavailable on modern Number Pads

0 (num-pad)	,		Location (modern '0' keys are wider)
+ (num-pad)	=		Location (modern '+' keys are taller)


	Keyboard keys that are unavailable on English keyboards

/		(blank)		Location (can only generate blanks in Kana mode)
' (apostrophe)	:		Location
=		^		Location
[		@		Location

	Alternates that are closer to the actual location of X68000 keys

]		[		Location
Return		]		Location (X68000 Return is shaped differently)
Backspace	\ (or Yen)	Location (certain modern keyboards only) (￥)

	Non-keyboard translations

Insert		LMB		Sometimes more convenient than Mouse Mode
Home		RMB		Location (normally to the right of the LMB key)



Drag and Drop:

Nearly any file you can load can be dragged and dropped onto the main window.
You can drop floppies, state files, hard disks, floppy archives, and MO disks.
You can even drop directories, which will become dynamically built floppies.

(Although the implementation is different, it is also possible to drag
and drop files onto the XM6 executable or a shortcut to the executable.
See the following section on command-line arguments for more details.)

It is possible to drop files of different types simultaneously.
For example, you could drop both a hard disk containing an installed
game and its corresponding boot disk at the same time. You could also
drop a state file set up for a special configuration along with the
disk images you want to use.

For a single floppy disk file, the destination drive is determined by
which side of the window it is dropped on. If a single file is dropped
onto the status bar, the nearest pane determines the drive to use,
including Drives 2 and 3. This can be overridden by holding down one
or more of the numerical keys 0 - 3, which will cause the file to be
inserted into Drives 0 - 3 respectively. Hold down '4' to insert the
same file into all four drives at once, which is not typically useful.
(If one simply wants to insert the same floppy into Drives 0 and 1,
it is better to use the Alt key, as described below.)

Multiple dropped disk images will be loaded into drives sequentially,
starting with Drive 0. The system will also be reset automatically
if Auto Reset is enabled (see the Misc tab in the options).

You can disable the reset feature by holding Control. Holding Shift
swaps the order if there are multiple floppies, or reverses the drive
to use (based on the window side) if there is only one floppy disk.

Holding Alt will cause the same file (floppies only) to be inserted
into both drives. This is most useful for multi-image files (such as
.zip archives) where the second drive will automatically receive the
second image contained within the file.

Holding Alt while dropping three or more floppy disk images will enable
Drives 2 and 3 to receive images as well. This is not useful very often.

If multiple images are dropped onto a floppy pane, rather than the
main window, then the excess images will be added to the history list.
If Control is held, the first image will not be inserted into the drive.

Similarly, multiple dropped state files will all go into the history.

 NOTE: When dropping multiple files of the same type, the order in which
 they are received by XM6 is determined by the OS and usually depends on
 which file was under the mouse cursor when dragging began. If the disks
 end up in the wrong drives, you could try repeating the operation with
 the shift key depressed.

If a single directory is dropped onto the main window with Control held,
that directory will become the current directory.

For non-floppy files, the drop location and state of the qualifier keys
(other than Control) do not matter.

Hard drive images will attach themselves to the correct interface,
possibly replacing an existing hard disk in your system configuration.
The system will be set up to use the new drive and will then be reset.
You can inhibit the automatic reset with the Control key. You must have
suitable SCSI ROM images installed in order to use SCSI drives. See the
SCSI section for details.



Command-Line Arguments:

XM6 accepts command-line arguments, which will be examined heuristically
to determine their type. Floppy disks, state files, hard disks, and MO disks
can all be loaded via this method. The term "floppy disk" includes archives
(namely .zip files) and directories (which become disk images dynamically).
It is permissible to mix different types of files, such as hard disks and
floppy disks. XM6 may rearrange the load order when multiple types appear.

Note that dragging and dropping files onto the executable, or a shortcut
to the executable (including on the Quick Launch toolbar) will cause those
files to be passed as arguments via the command-line interface. The same
applies to files passed using the Send To menu or via file associations.
Please see the note in the Drag and Drop section regarding how the OS
determines the order of the files.

If another instance of XM6 is already running, CLI arguments will be
passed to that instance instead, and the latest instance will terminate.
Therefore it doesn't matter much whether the program is already running.
Relative paths will be converted to absolute unless the path is invalid.
Passing arguments between Unicode and MBCS versions of XM6 will usually
fail or give unexpected results, although the MBCS edition can sometimes
figure out if its arguments are in the wrong format and then convert them.

Floppy disks will be loaded into floppy drives sequentially unless Shift
is depressed when the arguments are being parsed. Shift will swap the
order of the first two floppies or insert a single disk into Drive 1.
If Alt is depressed, a single floppy will be inserted into both drives.

If the first two floppy drives are supplied with the same file, either by
submitting the same file path twice or by holding Alt as described above,
and the file contains multiple disk images (as from an archive) then the
second drive will receive the second image from the set automatically.

This behavior also occurs if a multi-disk archive is the only floppy image
supplied and neither Shift nor Alt are depressed, unless the destination
drive is explicitly specified. (See below.)

Certain file types passed via this interface will cause XM6 to reset,
as will supplying two or more floppy disk arguments. The reset feature
can be inhibited by holding down the Control key.

If only one file-type argument is supplied, and it is a directory,
and Control is depressed, that argument becomes the current directory.

Arguments that begin with a dash or forward slash are subject to special
interpretation as described below. (Capitalization is ignored.)

     /Quit    causes XM6 to quit
    /Reset    causes XM6 to reset unless otherwise prohibited
  /NoReset    prohibits any resetting initiated by the current command line
/FullReset    same as invoking Reset and Clear from the menu

Delimited numbers from 0 to 3 specify the destination disk drive for the next
file argument. This has no effect for non-floppy-disk images at this time.



Software Keyboard:

XM6 has a powerful virtual keyboard that can be operated with the mouse.
Simply point and click on a particular key to simulate a keyboard press.

You can use the right mouse button to mark one or more keys as being
held down. This is useful for situations where certain effects can be
realized by holding down particular keys while a game boots.

Another use of the Software Keyboard window is to visualize various
inputs in order to e.g. check key bindings. Keyboard keys that are
depressed are shown in red. Keys containing LEDs will also appear
red if the LED is lit. An actively repeating key will be shown in
a slightly brighter shade of red compared to non-repeating keys.
(The LED keys are excluded even if they are being repeated.)

Note that if a key is depressed, but not being repeated, the OS will
lose track of its state after a reset. (Technically, the OS loses track
of every key; it's just that it will reacquire a key if it is still
repeating i.e. being sent at regular intervals.) Only one key can be
repeating at a time, so only one key, at most, will survive a reboot.
This behavior is important to understand if you are holding down keys
in order to signal a program to use a special mode as it starts up.

Controller inputs will be displayed as keys in blue or green depending
on the port. The numerical keys (1 - 8) represent buttons, and the
directional keys correspond to the axes. The ten-key pad visualizes
additional axes, if any.

Mouse inputs appear as magenta keys. The OPT keys represent the buttons.
Note that mouse inputs will only be displayed if circumstances warrant,
due to their potentially distracting nature.

The feedback provided by the Software Keyboard is also highly useful
when operating in special modes, such as Game Mode. If you want to
troubleshoot any sort of input problems, or simply wish to understand
what inputs the X68000 is receiving at any given time, your first move
should always be to open the Software Keyboard.

Hold down Shift when opening the Software Keyboard window to move
it outside of the frame window, to the extent this is even possible.
(Pop-up style windows are required, which is a configurable option.)
This feature also applies when opening it with the Alt-K accelerator.

Note that the Alt-K accelerator can also be used to close the window.



Game Mode:

This is an experimental alternate keyboard mapping. Unlike the standard
keyboard mode, this configuration is not user-definable.

This mode is not recommended when Controller Mode (see below) is sufficient.

You can turn this mode on or off by pressing Alt-G or Alt-Shift-G,
with the latter using a slightly different set of mapped keys.

The purpose of this mode is to provide a quick and easy way to switch
the keyboard layout to one that is more useful for games, which very
often use keys that don't exist on modern keyboards like XF1 or Touroku.

The strategy is as follows: Catalog the keys that are crucial for games
but are unassigned in the default keyboard configuration, then map them
onto keys which are rarely, if ever, used by games (ignoring situations
involving text entry).

Ideally, this mode will be compatible with as many games as is feasible.
Unfortunately, it turns out that quite a few of the letter keys are used
in high-profile games, and more are still being discovered. Therefore,
the key bindings are experimental and subject to change. The easiest
way to check them is to open the software keyboard and start typing.
You will then see what each key maps to.

There will be multiple key bindings for certain keys, such as XF1/XF2.
Some keys from the ten-key pad are available in the main keyboard area.
This was done for users who may not have a numpad on their keyboard.

NOTE: Certain system keys are mapped but may be intercepted by your
operating system. They may have undesirable side effects unless you
have disabled them somehow. There will always be other keys with the
same function that you can use instead, albeit with less convenience.
Kludges are used to reduce the impact, but they do not work perfectly.

NOTE: The Alt keys are mapped to extended function keys in this mode,
but they continue to function for activating menus and accelerators.
However, when used as system keys, extraneous input will be sent to
the emulated X68000. For example, pressing Alt-Q to take a screen
shot will work but will also activate the XFn and Q keys inside the VM.
(The particular extended function key depends on which Alt key is used.)
The same problem occurs outside this mode if you map the Alt keys in
the regular keyboard layout. (In both cases, this deficiency has been
partially mitigated but will still occur sometimes.)

While in this mode, the key translations used to make text entry on an
English keyboard easier will be disabled. Any keys which have not been
reassigned will retain the binding (if any) prescribed by the user's
configuration. The assumption is that said configuration will be similar
to the default mapping.



Keyboard Controller Emulation (Controller Mode):

The keyboard can be used to emulate joysticks and other controllers.
This feature does not interfere with the use of a real controller.
It will take priority over keyboard input, however. The rapid fire
feature is only available for real controllers.

The key assignment changes depending on the joystick type configuration.
Buttons are typically mapped to the letter keys in the first three or
four columns on the left side of the keyboard. Note that most games only
support the basic two-button Atari-standard joystick.

There may be multiple keys that map to the same controller button.
For example, the two-button joystick mode assigns A, S, D and Z, X, C
to buttons 1, 2, 1, giving the user several positions to choose from.
With a few exceptions, the directional controls are mapped to both the
numpad and the arrow keys.

The easiest way to see how the keys are mapped for a particular type of
controller is to use the Software Keyboard window as documented earlier.

The rapid-fire settings for this mode are taken from Device A in the
options (Tools > Options > Joystick > Setup) even if you do not have
a "real" Device A. Therefore, you only need to set the rapid-fire
settings once per game; these controller settings are preserved in
state files so you can switch between a real controller or the keyboard
at any time. If Device A has the same button configured multiple times,
this mode will use the rapid-fire settings from the last instance.
This is because earlier button assignments are more likely to be
non-rapid whereas duplicate buttons may have rapid-fire applied.

By default, Controller Mode is enabled automatically whenever it has
been deemed beneficial to do so, but you can disable this feature
under the Tools menu. You can also disable it temporarily in case
you like the feature but it is interfering with a particular game.

Note that it is not necessary to use the menu to temporarily disable it.
After it automatically turns on, simply toggle Controller Mode (Alt-J)
and automatic mode will be disabled until you restart the program.
You can turn automatic mode back on via the menu.

If Controller Mode is automatically enabled, it will also be turned
back off automatically the next time the VM is reset (unless you had
manually enabled it.)

Be aware that, with the default settings, Automatic Controller Mode
will not activate if a suitable input device is available on your
system. This is because a real controller is typically better suited
than the keyboard, and because such devices don't interfere with
keyboard input. (There are a number of games that accept both types
of inputs, with the keyboard playing an ancillary but necessary role.)



Dialogs:

Most dialogs that accept numerical input will treat it as hexadecimal.
If the default is decimal then the initial value will not be padded with
leading zeros.

You can force the input to be interpreted as decimal by prefixing the
value with a '#' symbol. '$' and '0x' are recognized as hexadecimal prefixes.

Most dialogs accepting addresses will also allow relative numbers:
if the number is preceded by a '+' or '-' sign, it will be added
to the original value. This feature is limited to addresses because
negative addresses aren't normally useful. For general data values,
the negative case is ambiguous: is it a number or an offset?



Status Bar:

The various panes/LEDs on the status bar have been expanded to include
some user interface features.

Files can be dragged and dropped onto the status bar. The drive (for floppy
disks only) will be determined by the approximate location: drop a disk image
onto a floppy pane to insert it into the corresponding drive.

Single- or double-clicking the FDD panes will have various effects depending
on the drive state and the qualifier keys, if any, being held down.

Single-clicking while pressing Shift will move the disk to the other drive.
The source drive will also be ejected unless it contains a multi-disk file.

Single-clicking while pressing Control will swap disks between drives.

Single-clicking while pressing Alt will insert the second-most-recent file.

Double-clicking without any qualifiers will perform "the most likely action".

The above operations will also work on Drives 2 and 3, even though there is
rarely any reason to switch disks between them.

Right-clicking a floppy pane will open a pop-up menu. This menu is similar
to the usual menu; the biggest difference is that the drive lock state
is ignored completely - disks can be ejected/inserted at will.

Caveats:

Using these features while emulation is paused can cause user confusion
because disk ejection/insertion requires a small amount of emulated time.
Disks may get queued awaiting insertion while emulation is paused.

Be aware that, aside from Alt, the above qualifier keys are likely to be
interpreted as X68000 input. This is usually not a problem, but it could
cause unexpected behavior in a few rare instances.



Menu-Based File System Browser:

There are a number of dynamic submenus located in several places within
the various menus. If one of them is opened, the local directory will be
scanned for relevant files, which will then be added to all the submenus.

All the dynamic submenus are linked, so opening one of them will cause
all of them to be built. For example, opening the "Nearby Images" menu
for floppy disks will also cause the Mass Storage menu to be built at
the same time, and its contents will reflect the state of the local
directory at the time the first submenu was opened.

The next time any of the submenus are opened, they will not be rebuilt
except under certain circumstances. Furthermore, the submenus are only
ever (re)built when they are opened. Therefore, even if you are loading
files from a directory with 10,000 disk images, there will be absolutely
no performance impacts (memory, I/O, CPU, OS handles) whatsoever unless
you actually open one of the submenus, and then only the first time.

When any of the submenus are reopened subsequently, the following checks
determine if the menus will be rebuilt:

- the local directory is different from when the menus were last built
- XM6 created a new file in the same directory since the last time
- the Shift key is currently depressed (i.e. the user forced a refresh)
- the current directory was previously selected under the "Go to" menu
- a menu item was previously selected but the file did not exist

Priority entries (listed at the top of certain submenus) are updated
if deemed necessary when a submenu opens. This is a low-cost operation,
even if the menus contain thousands of items.

Qualifier keys:

Holding Shift while opening a submenu will force a refresh.

Holding Shift while selecting a floppy disk image will cause it to be
inserted into the other drive.

Holding Delete while selecting a file will prompt to delete that file.
This does not work on directories.

Holding F2 while selecting a file (no directories) will give you the
opportunity to rename that file. Renaming files this way ensures that
XM6 is aware of the changes. The extension, if any, cannot be changed.

Notes:

You can press the key corresponding to the first character of a menu
item's name to select it. If multiple items start with the same
character, it will jump to the next matching item each time the key
is pressed.

The File Browser menu contains links to every other submenu and also
shows files of every supported type in a single list.

Selecting an item under the "Go to" submenu will change the local
directory, providing a means to navigate the file system without
affecting the VM. Selecting "Current" will force a refresh.

There is no reason to force a refresh unless you have added, deleted,
or renamed files in the local directory after the submenus were built.
(Additions or deletions performed by XM6 will be handled automatically.)

In Conjunction with Archives:

XM6 normally expects archives to contain only floppy images, and no more
than 16 at that. When archives that don't meet those criteria are loaded,
the browser menus are sometimes repurposed to display the contents of
the currently active archive instead of the local directory.

The functionality is largely the same in this case except you are seeing
the relevant files within the loaded archive.

The biggest difference is in the directory menu: although in-archive
subdirectories are supported, all files are shown regardless of their
path within the archive (the path will be included in the name, however).
Therefore, there is no need to navigate directories within an archive.

The ".." or Parent menu item will unload the archive from the browser,
taking you to the directory whence the archive resides. Archives are
also unloaded upon most actions that change the current directory.
The status bar typically alerts you when this happens.





 Options Reference (General)
------------------------------------------------------------------------

Key Mapping:

XM6 uses some sleight of hand to allow certain system keys to be usable
when mapped to X68000 keyboard keys, albeit not without complications.

The Windows keys are especially difficult to use in this manner unless
you prevent the OS from using them somehow. Otherwise you will end up
activating some system shortcut eventually.

The Alt keys can be mapped, but you will lose some of their menu functionality.
They will continue to function for activating accelerators (keyboard shortcuts).
However, extraneous input will sometimes be detected by the emulated X68000.
This is rarely a problem when playing games, but can be an annoyance during
text entry.

 Key Assignment Advice

F12 toggles Mouse Mode by default, but if your pointing device has a middle
button (and it is not disabled in XM6's options) then F12 can be repurposed.

F10 is reserved, by default, for opening menus. Once you are accustomed to
the program's interface, you may not need it anymore. In such a case, you
could remap the X68000 F10 key (normally mapped to your keyboard's F11 key)
to F10 and then repurpose F11. If unassigned, F10 functions as a Meta key,
although its location makes it somewhat inconvenient for that purpose.

Many older keyboards (such as the X68000's) have only one Control key whereas
modern keyboards have two. By default, only Left Control is mapped (although
there is some internal finagling to make Right Control work along with it).
If you believe you only need one Control key, you can repurpose the other one.
If you do so, you should make sure at least one of the Control keys is mapped
explicitly to the X68000 CTRL key. Test using the Software Keyboard window.

The grave/tilde key (~) can be mapped, but by default it toggles speed limiting,
which is probably more valuable than having an additional X68000 key available.

If you have one, the Apps key is useful when the menu bar is unavailable,
such as during full-screen mode. It also functions as a Meta key, which
is described elsewhere. Therefore, it is not recommended to map this key.

The most commonly used X68000 keys that are unavailable in the default key
mapping are as follows.

 XF1  XF2  OPT.1  OPT.2  HELP  Touroku(登録)

XF1 and XF2 are heavily used by non-doujin games, but are often superfluous
when in Controller Mode. Touroku and HELP are useful to have but, to the extent
they are recognized, they typically only need to be used briefly, such as while
a game is booting; the Software Keyboard window often suffices. The OPT keys
are used in a variety of different ways, but you may find that you don't need
them much. Experience will help you decide which of the above you need the most.

Unless you do a lot of text entry, the other unavailable keys not listed above
probably don't merit a key mapping in your day-to-day configuration. Game Mode
or the Software Keyboard can be used to input rarely needed keys.


Pop-Up Window Style:

XM6 allows the use of either child windows or pop-up windows. The former
cannot be active or receive input directly. They also are limited to
the client area of the frame window. Pop-up windows, on the other hand,
can be moved outside the frame window and receive the input focus.

That last feature is what enables most of the new input commands which
make pop-up windows so much more powerful. You can change the type
of subwindows with the "Options->Misc->Pop-Up Window Style" check box.


High-Priority Mode:

This elevates or normalizes the priority class of XM6 dynamically.

You can use this option to have XM6 play music in the background
while multitasking. If the audio still breaks up occasionally even in
this mode, you can try increasing the audio buffer size in the options
to 1000 ms (not recommended for general use due to high latency.)
Certain XM6 GUI operations can still break up the audio no matter what,
because they temporarily halt the emulation thread.

Caution: This can cause problems by shutting out lower priority tasks,
so please make sure your computer can handle the processing load first.
VM/MPU full-speed modes may, depending on the number of processors your
system has, be deactivated and unavailable while in high-priority mode
for this reason. This option is not currently saved.

A fast CPU and/or multiple cores usually make this feature unnecessary.


Dual-Mode FDD:

Allows all floppy drives to operate on double-density disk images.
X68000 drives typically only support the high-density format.


LED for FDD Motor:

This causes the floppy LED pane to reflect the state of the floppy
drive motor (excluding standby). It is enabled by default and it
emulates the behavior of real internal X68000 floppy drive LEDs.

If disabled, the LED panes (on the bottom of the window/screen)
will only illuminate during actual drive activity. This can save
a second or two of your time if you are waiting for activity to
cease prior to ejecting the disk image, but it is not realistic.


Fast Floppy:

If enabled, the speed of certain floppy drive operations will
be greatly increased. This is an excellent time saver but it
does have undesirable side effects for a few games.

Every game documented in the notes file is tested with this
option enabled, and any negative side-effects are written up.


Start in POWER-OFF State:

If enabled, the virtual power switch will be off when you first
start the emulator. Other than swapping disks, there isn't much
you can do in this state until you turn the power on using the
appropriate command from the File menu.


Update Boot Counter on Exit:

The X68000 SRAM contains a counter that is incremented during
the power-down sequence. Certain software may make use of it.

However, most emulator users do not press the power button;
they just quit the emulator, which is equivalent to pulling
the X68000's power plug. This setting compensates for that
by incrementing the counter on exit if the power is still on.

The SRAM.DAT file will only be saved on exit if the SRAM
contents have changed; therefore, if you disable this setting,
the SRAM.DAT file will be rewritten less often.


Blue Power LED:

Changes the color of the emulated power LED on the right side
of the status bar and in the version dialog (heh). That is all.

Could be useful for marking particular hardware configurations.


Parity Generation Circuit:

If installed, enables connecting SCSI drives via SASI (known as 'SxSI').

SxSI is an expert level feature and is inferior to genuine SCSI. The only
advantage is that it does not require any SCSI ROMs, but they are easily
obtained. The biggest disadvantage is that it requires special software.


Force 38400 bps:

Ignores the X68000's actual RS-232C baud rate and sets your PC's COM port to
use 38.4 kbps instead. You should only set this option if you have a physical
RS-232C MIDI interface or compatible device connected to your serial port.

The technical explanation is that, when using RS-232C MIDI, X68000 software
will set the SCC to the standardized speed of 31250 bps, but this baud rate
is not typically supported on PCs. So this setting forces the nearest match.
Some devices are capable of receiving direct serial input at 38400 bps.

As of this writing, XM6 now tries 38.4k automatically if 31.25k fails; however,
forcing it may still prove beneficial if the driver erroneously reports success.


Sound Buffer Size:

This is the length of the audio buffer expressed in milliseconds. This value
directly increases the audio latency of internally generated sounds (FM/ADPCM).
Larger values tend to decrease the risk of audible disruptions due to underflow.

The default is 100 ms which, by itself, is not enough latency to be perceptible,
although additional delays along the audio chain could increase the effective
latency into the 200+ ms range where it might become noticeable to some people.
(Please do not confuse this with video latency, where even 20 ms is suboptimal.)

Although 100 ms is reasonably low latency for audio, it might be insufficient
to prevent the occasional disruption of the audio stream. Even systems with
ample processing power and low utilization can suffer brief audio drop-outs
due to interference from other software running in the background.

If you are hearing occasional distortions in the audio, increasing the buffer
size may help. Due to the increase in latency, it is not recommended that you
increase the buffer size if you are not having problems. Also note that even
the largest setting (1000 ms, or 1 second) might not eliminate disruptions
entirely if there are problems somewhere else in the audio chain. For example,
a sound card of mine started producing crackles in the analog output due to age,
and a particular hardware configuration had problems when Hypo Threading (sic)
was enabled. Such problems would occur with other audio programs as well though.

Absent any noticeable latency or buffer underflows, the only reason you might
want to tweak the buffer size is to help synchronize the FM/ADPCM output with
the audio from any MIDI devices you might be using. The recommendation in such
a situation is to first try adjusting the MIDI output delay (documented later)
before changing the buffer size.


Sound Buffer Polling:

This setting determines how often the audio buffer is checked. Larger values
increase latency as well as the likelihood that the buffer will underflow.
Lower values reduce performance because mixing and audio driver interfacing
events become more frequent.

The polling rate is disregarded if the buffer size (see above) is very small.


FDD Icons:

This option enables informational icons in the floppy panes on the status bar.
The icons are described below.

Check mark:

The disk is in a primary drive.

Green arrow:

The disk is in a secondary drive.

Yellow arrow:

The disk is in a tertiary drive.

Red arrow:

The disk is in an incorrect drive.

Question mark:

The drive usage has not yet been investigated for this particular disk image.

No icon:

The disk image is unrecognized, is in an unsupported format, or is modified.

The arrow icons point towards the disk's primary drive. Drives 2 and 3
can never be primary drives, so most arrow icons face left.

Primary drives are drives that a particular disk is best suited for.
In most cases, a disk image should be inserted into its primary drive.
A few games are flexible enough to accept one or more disks in either
Drive 0 or 1; such disks will have both drives marked as primary.

A disk flagged as being in a secondary drive indicates that the image is known
to have some use in that drive, but it may not be what you intended. One example
is a disk that can be booted to enter a special mode, such as user disk creation
or a sound test. Disks that are fully usable in Drives 2 and 3 will receive the
secondary drive indicator.

The tertiary drive icon is rarely used. It means that the disk can be used in
that drive but it is unconventional and could be suboptimal, possibly causing
problems later on. It is not obligatory to move the disk, however.

If a disk is in a drive for which it has no known purpose, the red icon will
be displayed. For convenience, the recently-used menu of the primary drive
will be populated automatically in this case.

Please be aware that just because a disk is flagged as being in the wrong drive
it does not necessarily mean that the disk must be moved at that point in time.
For example, some disks are only used for creating user disks, so moving such
a disk to its primary drive will not do anything useful until you enter the
user disk creation mode. Many of these tricky cases are described in the notes.

Conversely, even though a disk is in the right drive, it may not be needed there
at the moment. This is a common occurrence for games having three or more disks.
There simply isn't an easy way to detect which disks are needed at a given time.

 TIP: If drive icons are displayed, there is a higher probability that notes
 will be available for that game.

Drive icons will only be displayed for a few seconds. They will not be displayed
for disks inserted automatically as a consequence of loading a state file.


SASI/SxSI/SCSI:

The default SASI interface can be used to connect up to 16 hard drives
of limited size.

SxSI allows the user to connect SCSI devices through the SASI interface;
however, it requires special software in order to function and therefore
is not recommended.

SCSI supports larger hard disk drives as well as magneto-optical and
compact-disc drives. It requires additional ROM files to function:
SCSIEXROM.DAT (external SCSI) or SCSIINROM.DAT (internal SCSI).

The biggest practical difference between external and internal SCSI
is that the former can coexist with SASI in XM6. "Internal" in this
case means that it is an integral part of the emulated X68000 model,
whereas "external" means it is an add-on for a model utilizing SASI.

External SCSI is similar to installing a CZ-6BS1 SCSI board.
Internal SCSI was used in X68000 SUPER and later models.

You should reset the system after making any configuration changes
to the above.

To verify that an interface is working properly, boot Human and run
SWITCH.X: HD_MAX will show a number if SASI is working, and SCSI_ID
will show a number (usually 7) if SCSI is available.


Mouse Modes:

There are two new settings under the Mouse tab in the options: Linearize
and Pointer. These settings combine to generate different modes:

* Enabling Linearize only is known as Linear Mode.
* Enabling both of these settings gives you Pointer Mode.
* If they are both disabled, you get XM6's original mouse behavior.

Enabling Pointer without Linearize is not known to be useful at this
time and is therefore not considered a distinct mode.

The modes themselves are described in more detail below.

These new mouse settings are both enabled by default. They are also
saved in state files. If you load an older state file, the current state
of these new mouse settings will not be affected, which may or may not
be what you want, but it is generally preferable compared to resetting
your mouse configuration every time you load an old state file.

Because these configuration items are stored in state files, one can
switch mouse modes simply by loading a pre-configured state file.
(This technique is applicable to many other settings as well, not just
mouse modes.)

Although they are not stored in state files, there are now three mouse
speed settings: one for each of the modes. They are stored in the .ini
configuration file. One can therefore adjust the speed independently
for each of the modes.

Pointer Mode:

This mode requires both the Pointer and Linearize mouse options to be
enabled, which is the default.

Pointer Mode attempts to mimic the motion of your operating system's
mouse cursor. Presumably you are most familiar with the way your own
mouse moves, so this mode should be ideal for point-and-click software.
This mode normally requires the Linearize setting to be active in order
to function properly; otherwise the motion will most likely be unusably
jumpy. Nevertheless, it is possible to turn off Linearize while in
Pointer Mode, just in case there exists otherwise-incompatible software
that becomes functional with such a combination.

Note that if the X68000 screen is being stretched, as in full-screen mode,
the X68000 cursor will necessarily move farther on your display than your
OS cursor does, due to the pixels being enlarged. The relative distance
traveled (in pixels) should be the same though.

Because it is based off of the OS mouse, the Mouse Speed ratio setting
should normally be set to 100% in this mode, although you can adjust it
if you wish. Another consequence is that changing your OS mouse settings
may also affect the way this mode works.

Linear Mode:

This mouse mode takes effect when only the Linearize setting is active -
the Pointer option must be disabled in order to use it.

This mode is intended for games that require aiming. It is less useful
for point-and-click software, although it will still be usable in most
cases and may even be preferable to the original mouse mode.

Linear Mode attempts to make mouse motion more consistent. It isn't
compatible with every program, but to the extent it is, fast and wide
motions will be smoother and more consistent but may also require you
to move your mouse farther than in the usual mode. Consequently, it may
be beneficial to use a higher Mouse Speed setting when in this mode.

If used with incompatible software, you won't be getting any benefits
but the results may still be reasonably functional, particularly if you
have increased the mouse speed. A consequence of this is that it is
difficult to confirm incompatibility empirically.

Original Mouse Mode:

If you turn off both the Linearize and Pointer options, you will get
the classic mouse behavior.

This mode won't have any additional compatibility problems that the
other modes might incur, but it tends to be less smooth.

Mouse Mode Summary:

* Pointer Mode - best for point-and-click
* Linear Mode - good for aiming; tends to be slower
* Original Mode - most compatible, albeit not necessarily noticeably so


Joystick > Type:

This configuration item allows you to select the type of emulated input
device attached to either port. In other words, this determines how the
input device(s) attached to your computer will be seen by the X68000.
No input device type is compatible with every game, and if the wrong
one is selected, it can cause all manner of problems.

A two-button, Atari-style joystick is standard on the X68000. Most games
that accept controller inputs will support this type, which is why it is
the default. It is the least likely to cause problems.

There is also a model that adds Start and Select buttons. These extended
buttons are signaled by combining opposite directions (i.e. L+R or U+D),
which may cause minor problems if unrecognized. Note that this is the
only controller type emulated by XM6 that supports these special inputs;
the rest send their additional buttons as direct inputs. The FMT-PD102
(FM Towns Pad) seems to be equivalent except Start is labeled Run.

The other controller types are only usable in a small number of games.
They are not recommended unless you are playing a game that specifically
supports one of them.

That said, the devices listed below should be compatible with software
expecting a standard, two-button, Atari-style controller, although the
two functional buttons may not be in the expected location. The extra
inputs will only be recognized if the software is deliberately looking
for them.

Cyberstick (digital mode only)
CPS Fighter (both SFC and MD)
Magical Pad
XPD-1LR

The following types are not Atari compatible at all:

Cyberstick (analog mode) and compatibles
Megadrive / Genesis gamepads

You should only select the above types when playing certain games.
You may need to perform some sort of in-game action to enable them,
unlike the others.

Special devices:

The XPD-1LR, mentioned above, is intended for playing Libble Rabble,
and has both left and right directional controls to accommodate this.
It is largely interchangeable with most of the other joystick types,
although its right-side axes probably won't be interpreted correctly.
It is also supported by Crazy Climber.

Electrically, the Pac-Land controller is equivalent to an Atari-style
input device that is only capable of sending Left, Right, and Button B.
It is probably only useful for playing Pac-Land, although a standard
joystick will also work for that game, albeit not quite as easily.
It has three buttons and no directional controls.

The BMPad is electrically equivalent to a two-button, Atari-style
controller. The only practical difference is that it uses buttons
instead of axes, and the layout is only suitable for playing BM68.


Joystick > Device:

This is where you select which physical controllers (if any) to use for
your emulated X68000 input devices.

Any suitable controllers attached to your computer should show up
automatically. Device A is for the X68000's first port and Device B
is for the second port.

Your controller's axes and buttons are assigned automatically, but the
latter can also be manually reconfigured by clicking the Setup button.

Note that it is possible to assign the same emulated button to multiple
physical buttons, possibly with different rapid-fire settings. There is
also the rarely needed ability to assign buttons for both X68000 ports
to the same physical controller, or split an emulated device's buttons
between two physical controllers.

An easy way to test controller inputs is to use the Software Keyboard,
which is explained earlier in this document.

Note that input settings are saved in state files, so one can create
different profiles for different situations and save them as separate
state files, to be loaded as needed.


Run-Length Encoding:

By default, run-length encoding (RLE) is applied to state files before writing
them to disk. RLE is only available for the Unicode edition; the MBCS version
has a compatibility requirement for its state files, although it can still read
state files with RLE applied.

RLE can greatly reduce state file size at the cost of slightly slower saving,
which typically only adds a few milliseconds and is unlikely to be noticeable.
The reduction in file size may cause the file to be written to disk faster.

RLE can be configured using the relevant menu items under File > Advanced.
RLE can be disabled entirely in case you are modifying state files directly
for some reason. Disabling it may also have a placebo effect if you believe
that saving is taking too long, but unless you have a very old, very slow,
single-core CPU paired with aggressive write caching, you are unlikely to
notice a performance degradation.

The other configuration option for RLE is how heavily it is applied.
The heavier settings reduce the file size but decrease compressibility.
Lighter settings don't reduce the file size as much but the resulting
file(s) are better suited for archiving with 7-Zip, often compressing
better than identical data without RLE applied!

Each setting corresponds to a different value for the minimum run length,
which in turn controls the encoding process. This value can be arbitrarily
set by editing the .ini configuration file, if you are the curious type.

For performance reasons, minimum run lengths below 9 will be rejected.
Values as low as 4 have been tested and could be supported in theory,
but would require a separate encoder and/or additional memory.

 Implementation Details

RLE will almost always reduce the size of state files; but if no suitable runs
are found, this particular implementation will write the file out uncompressed.
The RLE is done in one pass, so there is no performance penalty in this case.
Realistically, this can only happen if the minimum run length is set too high.

Theoretically, this RLE implementation can produce files that are larger than
the original, but it would require a carefully constructed state file that only
has one or two runs of length insufficient to overcome the encoding overhead.
This probably cannot happen naturally.

RLE works very well when VM RAM is relatively clean, meaning that the unused
parts of memory are all initialized to zero, which is the case when XM6 is
first started. RLE performance will degrade as more VM RAM is written to.
This degradation will usually persist after memory is deallocated by X68000
software. It will even remain after a reset, because resetting does not
reinitialize RAM, by default. (The Reset and Clear command should be used.)

 Note that state files contain all the VM's RAM, so the actual amount
 of entropy within the VM will change whenever a state file is loaded -
 it is not the same thing as resetting.

Also note that the deleterious effects of entropy are not exclusive to RLE;
even LZMA will suffer a reduction in compression performance when there is
unused junk in X68000 RAM - it's just that LZMA is much more sophisticated,
so the impact will be reduced, especially when compressing multiple state
files that all have identical unused junk (assuming the dictionary size is
sufficiently large).

RLE state files may have a CRC attached. For performance reasons, this is only
done if hardware support is available. The CRC is calculated from the original
input data rather than the RLE output. It is calculated during the same pass
as the encoding in order to take advantage of caching.

During decoding, the CRC is checked (if hardware support is available) and the
file will be rejected if the check fails. Therefore, this RLE implementation
(which is my own design) is shown to be reliable every time you successfully
load a state file. It should only fail to load if the file itself is corrupt,
due to a faulty storage medium, truncation, intentional tampering, etc.

 Recompression

A run-length-encoded file can be compressed nearly as well as one without
encoding. However, a group of files with RLE applied will suffer a small
reduction in compression performance, even with a sufficiently large dictionary
size. This is because the encoding information itself is not very compressible.
This reduction can be allayed by applying RLE lightly, such that only the runs
which are sufficiently large are encoded.

The minimum run length parameter affects how well the file can be recompressed.
With subsequent LZMA (7-Zip) compression, small values reduce compressibility.
As it increases, recompressibility will more or less steadily increase, even
resulting in gains over LZMA alone. As it continues to increase, the gains
start becoming chaotic. Somewhere around that point tends to be the point where
the maximum LZMA recompressibility is found. Beyond that point, the gains start
to plateau but are still chaotic without forming a proper asymptote.

The results from compressing multiple RLE files with LZMA follow a trajectory
similar to the single-file case but not such that the optimal minimum length
could be reused when compressing multiple files, even for files from the same
context. Notably, the trajectory tends to be expanded, with the optimal value
found further out, compared to the single-file case.

In both cases, the optimal minimum run length parameter will vary depending on
the data, which makes it difficult to choose a general-purpose value. The gains
or losses tend to be on the order of ones or tens of kilobytes, which may not
be worth the effort of optimizing. An extremely high minimum run length tends
to produce mediocre gains but without much risk of reducing compression.




 Options Reference (MIDI)
------------------------------------------------------------------------

There are two MIDI pages in the options: MIDI and RS-MIDI, the latter of
which is described later and is not recommended for beginners. The former
configures an emulated MIDI board, nominally a Sharp CZ-6BM1 but also
compatible with System Sacom's SX-68M.

Most of the settings described below apply to both configuration pages.


Reset Command:

This option determines the type of reset command that will be sent
to the selected MIDI output device on a reset.

If your device is relatively new (1992 or later), GM (General MIDI)
is the safest choice. For newer devices made by Roland, try the GS
setting. Older Roland devices (before 1991; e.g. MT-32 or double-digit
CM modules) typically need the LA reset command. XG is only applicable
to newer Yamaha products, starting around 1994.

Unless your MIDI instrument or software synthesizer is an LA type,
the reset command isn't critical; choose GM or GS if you are unsure.
Most likely you will not notice a difference whichever you pick.

XM6 will attempt to select the correct command for you; whenever you
change the output device in the options, it will examine the name and
try to predict what sort of synthesizer it is. Obviously this won't work
for hardware devices connected via a MIDI cable.

If the device is producing wrong sounds even after a reset, either try
a different reset command or cycle the power on the hardware instrument.
(For software synthesizers, you can simply restart XM6.)

If Control is depressed while selecting a reset command, the command
will be issued to the device. (It will not account for unapplied changes
to the output device, however.) Double-clicking also has the same effect.
Normally, modifying the reset command will not issue a reset until an
actual reset event occurs or the selected device has changed.


Output Delay:

The output delay value is the number of milliseconds the MIDI thread
will wait before sending a complete MIDI message after the VM submits
the final byte of the message.

The default value formerly was 84 ms, which is a bit high. The original
author never documented the reason why such a precise number was chosen.
Limited testing suggests that this much latency does not yield accurate
results as compared to a real machine. See also footnote (1) just below.

Therefore, the default delay value is now 20 ms, which should cause
MIDI sounds to have low latency relative to FM/ADPCM sounds and the
VM in general.

Reducing the delay value even further is possible but it can cause
performance to decrease and jitter to increase. Most likely you won't
notice a difference either way. Furthermore, some drivers are very
stable whereas others have tens of milliseconds of jitter, so the
additional jitter caused by little or no delay could end up being
inconsequential.

Also note that Roland requires a 20 ms delay after "large" messages
sent without handshaking for most of its contemporaneous models
(the exception is 40 ms for the MkII variant of the SC-55).
This restriction is usually irrelevant to you the emulator user,
but you could run into problems if you interrupt the VM while
it is transmitting large MIDI messages by subsequently loading
a state file that immediately starts sending MIDI messages. 
A 20 - 40 ms delay would give the MIDI device sufficient time
to finish processing the last sent message (if any) from the
previous state.

If MIDI notes seem to miss or stumble, try increasing the delay.
You should also adjust the delay value if you believe MIDI sounds
are resounding at the wrong time compared to the VM action or the
FM/ADPCM sounds. (In the latter case, you could also try adjusting
the sound buffer size, documented elsewhere.)

The delay for RS-MIDI (described below) can be either absolute
or relative (the default). A relative delay means that the value,
positive or negative, is added to the configured delay of the
first MIDI device to calculate the delay of the RS-MIDI device.
The default is a relative delay of zero, meaning that it will
use the exact same delay value as the MIDI board. You may wish
to decouple the two devices by disabling the Relative Delay
setting. This may be useful for devices having large amounts
of inherent latency.

Changes to the delay value take effect immediately, but if you
do not have something audible to compare it to (e.g. FM sounds
or a second MIDI source) then it might seem like it has no effect.
(You may hear some stumbling only at the moment the delay changes;
this is normal and does not indicate a problem in itself.)

Clicking the text on either side of a delay spinner control
will toggle the value between its default and minimum.

(1) 84 ms is 262.5 bytes at 31250 baud. Roland places an upper limit of 256
bytes on DAT/DT1 messages without clarifying which parts of the message count
towards the limit. Legal messages could potentially be as large as 262 bytes
(~84 ms) or even 266 bytes (~86 ms). (One MIDI byte is 320 microseconds long.)
while this might explain the derivation of the former default delay setting,
the only reason I can contrive to apply this much latency is to give the MIDI
chain enough time to transmit a fully buffered 262-byte message that could be
pending from a previous state/application. It is hypothetically possible that
you could end up overflowing some buffer of insufficient capacity for two large
DAT/DT1 messages. If you are using hardware MIDI synthesizers, and want to
eliminate this possible source of dropped/incomplete messages, then a delay
of at least 106 ms (126 ms for MkII SC-55) would be prudent. (This value is
86 ms -- the 266-byte period -- plus the 20 or 40 ms delay noted earlier.)


Input Device:

Most hardware devices have three MIDI ports: Input, Output, and "Thru".

For games, only the output port is critical. The input port may be used
for handshaking, which increases speed and reliability for data transfers,
but if it is not connected, most games will still load their customizations
using a fallback unidirectional mode.

This is fortunate because the vast majority of software synthesizers do not
have the ability to send MIDI Input messages; if there are any games that
require handshaking (or request data), most people will be unable to fully
enjoy them for this reason.

If you have the option, set the input device to match the output device,
or simply disconnect it altogether.


Output Device:

This setting determines which MIDI device (hardware or software) installed
on your system will receive the X68000's MIDI commands. Most users will
only have, at most, one "real" device - the MIDI Mapper does not count.

The MIDI Mapper is almost always a deficient interface for whichever
device is configured to be the default on your system. In nearly every
case it will not sound any different than selecting the first device
listed immediately after it, usually the "Microsoft GS" synthesizer.
It does sometimes provide a working vehicle for buggy MIDI drivers,
but only if you have the means to configure the device it maps to.

Changes to the input/output device won't take effect until you hit OK.


RS-232C MIDI:

Originally, MIDI on the X68000 was realized through expansion boards.
Later on, it became possible to use the machine's serial port connected
directly to a compatible MIDI instrument (such as the TG100) or through
an RS-232C MIDI interface. This is colloquially known as "RS-MIDI".
The standard serial MIDI product for X68000 was System Sacom's SX-M232.

RS-MIDI appeared late in the platform's life, so most MIDI software only
supports "board" MIDI (and Roland LA-class devices). A number of games
do support both interfaces. One game (Lodoss II) is known to support
both interfaces simultaneously.

If you have the appropriate hardware attached to your PC's serial port,
XM6 can make use of it (when running RS-MIDI compatible X68000 software).
In the options, go to the Port page and configure it to use whichever
COM port is connected to your MIDI device. Usually this will be COM1.

Very few people will have such hardware connected to their computer,
however. Instead, you can redirect the emulated X68000's serial port
to a MIDI device similarly to the way MIDI emulation works. In the
options, navigate to the RS-MIDI page and click Enable. The RS-MIDI
configuration is very similar to that of the MIDI board; basically
it is just a second MIDI pathway that a limited number of X68000
programs can make use of.

Any software with RS-MIDI support will have been published after the advent
of General MIDI and will most likely support it (or the similar GS standard).
Therefore, a good strategy is to keep your LA-class device (if you have one)
connected to the MIDI board and assign your GS/GM device to the serial port.
That way you can switch between two (or three, including FM) different music
scores simply by telling a compatible game to use either board or serial MIDI.
You will still have to manually switch the MIDI board device back to GS/GM
for board-only games that don't support LA, but not as often.

Another rule of thumb is that it is not generally useful to redirect RS-MIDI
to the same output device as the MIDI board; probably every piece of X68000
software that support RS-232C MIDI also supports a MIDI board, so if both
output options (in the X68000 program) have the same effect in your XM6
configuration then you haven't gained anything from the RS-MIDI feature.

The RS-MIDI configuration is only saved in state files if RS-MIDI is active,
meaning that a valid MIDI message was sent through the serial port since the
last reset. That probably won't occur very often; the intent here is to avoid
unnecessarily disturbing your current configuration every time you load an
old state file.


Device Sharing and Double-opening:

Double-opening is hereby defined as the situation where the configured RS-MIDI
device is the same device being used by the MIDI board. In this case, XM6 will
attempt to open the same MIDI device twice. Usually this fails. Software MIDI
devices are able to create multiple simultaneous instances of their virtual
device for each client; most will not do so, however.

If double-opening fails, XM6 will instead share the MIDI device between the two
X68000 MIDI sources (MIDI board and RS-232C MIDI). This works fine as long as
only one source is in use at a time, which is almost always the case.

Due to aliasing, you might have a double-opening scenario without being aware
of it. For example, if one MIDI source is configured to use the detestable
MIDI Mapper, and the other source is configured for the same device as the
MIDI Mapper, the second source will effectively be opening the same device
a second time.

Due to the above complication, XM6 (usually) assumes that an allocation failure
when attempting to open a second MIDI device is caused by device aliasing
and will then fall back to sharing. Therefore, one of your MIDI devices might
actually be shared even though both sources appear to be configured to use
different devices.

Again, sharing is not normally a problem. It only matters if both sources are
being used simultaneously, and only Lodoss II is known to be capable of that,
and then only if configured to do so. (Lodoss II was, in fact, the impetus
for adding RS-MIDI redirection to XM6.)

In that particular situation, sharing defeats the purpose of attempting to
output to two separate devices: if you don't have two distinct devices then
you aren't improving your audio experience because the notes from one device
will preempt the notes from the other. However, you can still prove to yourself
that it works by increasing the relative delay values between the sources until
you can hear both sets of notes resounding.

For non-simultaneous board/serial MIDI output, which is almost always the case,
sharing has no issues, and keeping the relative delays the same is fine.

One additional noteworthy consequence of device sharing is that two sets
of reset commands will be issued to the same device. That in and of itself
is not harmful, but if the reset commands are different then you may not
get the results you were expecting. For example, setting board MIDI to GM
and serial MIDI to GS might seem like an easy way to switch between the
two standards, but it only works if you are also using two separate devices,
or a single software synthesizer that allows double-opening; if a single
device ends up being shared then the above strategy won't work as intended.


MIDI Caveats:

If you add/remove a virtual MIDI board, you must reset the VM. You should
also reset the VM after enabling RS-MIDI; otherwise certain software will
fail to detect that it is connected. You should typically reset after
switching to a different output device, to ensure that the correct
custom instruments (if any) get loaded. When in doubt, reset.

The state of external MIDI devices cannot be recorded in state files.
Therefore, you may get incorrect MIDI behavior when reloading state.
Typically this manifests as unexpected sounds due to wrong "programs"
being assigned to channels and/or custom instruments not being loaded.
(The latter is mostly only a problem for LA MIDI. A workaround is to
start the game, so that the instruments load, and then reload state.
The channels may still have the wrong instruments assigned, however.)

Many cheap USB MIDI cables cannot reliably send more than 3 bytes at a time.
Therefore, System Exclusive (SysEx) messages cannot be sent using such cables.
This problem cannot be solved at the application level, but better drivers
could possibly fix it. (SysEx messages are used for customizing instruments,
among other things. Without them, some music will sound absolutely terrible.)

Adding/removing MIDI devices or altering your MIDI Mapper configuration (*)
can cause problems due to the device indices changing. XM6 stores the
configured device index in state files and its configuration file,
so if the indices change, a different device will end up being used.
You should always restart XM6 and verify its MIDI configuration whenever
you make any of the changes discussed in this paragraph.

* This includes changing your computer's default MIDI output device!





 Options Reference (Graphics)
------------------------------------------------------------------------

Full Screen Resolution > Do Not Change:

This option is enabled by default. If disabled, entering Full Screen
mode will temporarily change your display resolution to 800 x 600.
Otherwise Full Screen mode will enlarge the window to fill the screen
at its current resolution, which is much faster and less disruptive.

This menu item was formerly named Full Screen Stretch.

If the screen resolution is high enough, it will stretch to integer
multiples of the original image (including horizontal stretching),
producing an aliasing-free picture. You may need to turn off the
status bar to reclaim the entire vertical area in order to reach
qualifying resolution thresholds.

A minor caveat is that it will not do any stretching if the emulated
system is in a resolution commonly used for text display and your screen
resolution is very low, since the results look bad without any benefits.

This option, like most of the View settings, appears in the configuration
file but will not be stored in state files.


Full Screen Resolution > Never for Primary:

If you set "Do Not Change" (see above) to disabled, the resolution of your
screen will be changed when switching to full-screen mode, if possible.
This change is temporary and will be reverted when leaving full-screen mode
or exiting the program (even if you end it forcibly for some reason).

However, by default, this program will never change the resolution of your
primary display, because that can be confusing or inconvenient. You can
disable this safeguard by disabling this menu item.

If you only have one usable display then you necessarily must disable this
setting (and the one above) in order to use the resolution-changing feature.


Full Screen Maximum:

If enabled, this setting causes full-screen mode to fill the entire available
screen area (excluding the status view on the bottom, if such is enabled).
Because the dimensions of the original image are ignored, this can result
in unnatural aspect ratios and distortion under many common circumstances,
although disabling the status bar may help somewhat.

If this setting is disabled, the default behavior is to only stretch the image
by integer multiples until the height or width of your screen are exhausted.

(There may be an additional horizontal stretching factor applied beforehand,
which isn't necessarily integral. Furthermore, in rare cases, there may not
even be enough vertical resolution, and so the image will be squashed in order
to fit your display. Ideally you want at least 1024 vertically, and that's
only guaranteed to be sufficient if the status bar is turned off.)

(Another aside: integer multiple scaling is also subject to vertical truncation,
which means that, if the display's vertical resolution falls short of the image
height by a small margin, the bottom of the image will be truncated in order to
avoid the distortion caused by shrinking. This even applies to window mode.)

While full-screen, the mouse wheel will turn this setting on or off,
in addition to its usual function of adjusting stretch settings,
as described later on.


Full Screen Rescale:

Enabling this feature will cause Full Screen Stretch mode to ignore
the scaling factors associated with the virtual screen resolution.
This sometimes produces better results for some screen resolutions,
although it may look unrealistic in other cases.

For example, a 256x256 image displayed in low resolution will normally
be doubled to 512x512 prior to the full-screen stretching/scaling
calculations, but with Full Screen Rescale enabled, the 256x256 image
will be scaled directly to integer multiples, allowing otherwise
unachievable stretch factors such as 3, yielding 768x768. With this
option disabled, the first integer multiple is 2, yielding 1024x1024,
which requires a higher resolution monitor than the former.

Another use for this is to "correct" the aspect ratio of certain games,
most commonly those operating in the 512x256 family of resolutions.
The results won't be as accurate compared to a real X68000, but often
look better.


Smoothing:

This option causes a smoothing effect to be applied whenever stretching
by a non-integer multiple. This happens frequently with certain stretch
modes and occasionally due to emulated video modes that have too much
vertical resolution (e.g. a height of 1024 will always be compressed
in windowed mode and possibly in full-screen mode depending on your
display settings.) Full Screen Maximum is almost always non-integral.

This menu item is disabled at times when stretching is being done by
integer multiples (or not at all) because it would have no effect.

When it takes effect, aliasing will be reduced but the picture will
appear fuzzier and possibly darker. It also tends to be slower.

Enabling smoothing sometimes cures problems with defective video drivers
but only when stretching is being performed (hence the feature noted above
where this menu item will be disabled when inapplicable).

Enabling smoothing can also cause visual problems, and because it is
entirely implemented by the video drivers and/or OS, effects vary.


Stretching / CRT Effects:

If enabled, CRT effects and horizontal stretching will be applied.
If disabled, the image will appear perfectly centered at its exact
horizontal resolution, albeit with hardware scaling still applied.

The CRT effects mostly cover image positioning, which is used in
rare situations for rolling-in the screen and similar things.

The mouse wheel will turn this option on or off, in addition to
(sometimes) changing the stretch mode as documented below.


Horizontal Stretch Mode:

If stretching is enabled (see previous option) this setting controls
the degree by which the image is stretched horizontally. Please be
aware that the stretch mode that will be used is highly dependent
on the emulated screen mode; certain modes will ignore this setting
or will only allow horizontal stretching to be turned on or off.

The selection of modes is experimental, and there is no mode that
works perfectly under every situation; therefore this setting is
not saved anywhere.

There is no menu interface for this setting; it can only be changed
via the mouse wheel at this time. When changed, a message will be
printed in the status bar informing you what the new setting is.

The 1/4 and 1/3 modes tend to be better representative of what
a real system historically looked like, but CRT devices had
a lot of variation and monitors could be adjusted by the user.
Please use whichever mode suits you for each game.

1/4 or 1.25:

This is the default mode. It is also what XM6 used historically.
It is a good, conservative setting.

A base image with a width of 512 will stretch to 640 in this mode.
This makes it ideal for games that switch video modes; the images
are more likely to have the same resulting dimensions regardless
of which screen mode the game is using at a particular time.

1/3 or 1.333:

This mode tends to have the most aliasing, so you may want to use
the smoothing option. Its intent is to provide an "aspect ratio"
of 4:3, even though that term is misapplied in this case.

Note that if you measure the visible width/height, you will most
likely not get a calculated ratio of 4:3, but this is meaningless.

In 15 kHz mode, the stretch factor will be 1.35 instead.

1/2 or 1.5:

This mode may look too wide for some games, but it tends to have
the least amount of aliasing, especially for text printed with
thin fonts. (For certain modes, it is implemented internally
by multiplying the base image by 3 instead of 1.5, in fact.)

A base image with a width of 512 will stretch to 768 in this mode.

2/1 or 2:

This mode is not even remotely realistic. It is only provided
because it "corrects" the aspect ratio of the default screen
mode of certain games, namely those published by Capcom.

Ideally one would enter the game's option mode and set it to
use a wider screen mode, but using this stretch mode works
as an alternative.

Note that in most cases you will not even be able to select
this setting in windowed mode, because the resulting image
would be too wide for the window.


Scanline Simulation:

If enabled, more accurately simulates the scanlines of non-interlaced
15 kHz video modes. In such modes, the even/odd fields overlap to
produce a low-resolution progressive display (think "240p") which
has more space between the scanlines than you would see in 15 kHz
interlaced modes (think "480i"), which are, incidentally, almost
never used on the X68000 - I only mention them to help describe
low-resolution non-interlaced modes in terms readers might know.
(Double-strike mode is another term, albeit not commonly used.)

Be aware that most games default to 31 kHz modes, so you might not
see any difference when using this setting unless you specifically
configure games to use a low-resolution mode. (Most 31 kHz modes
are progressive - think "480p".)

At the moment, this only simulates idealized scanlines. Even on RGB
monitors, real scanlines are much thicker when illuminated such that
the unilluminated space between them appears very thin, even more so
the brighter the lines.

If non-integral vertical stretching is occurring, the concomitant
aliasing produces a particularly poor image with this setting active.
In such a case, either disable this option, turn off full-screen mode,
or try to adjust the stretching. (Full Screen Maximum tends to produce
non-integral vertical stretching, especially in conjunction with the
status bar. Changing your computer's display resolution can also affect
full-screen stretching.)





 Full-Screen Display / Multi-Monitor Reference
------------------------------------------------------------------------

The View > Full Screen Display submenu allows you to set your preference
for which display/screen/monitor (these terms are used interchangeably)
will be used when entering full-screen mode. If your system only has one
display then the submenu will be inactive.

When making a selection, you may hold down certain qualifier keys.
The effects are described below, followed by explanations for each
of the preferences. Note that some settings are shared with the
frame window startup settings, but not the qualifier keys.

 Qualifier Keys

Hold Shift to make the selection temporary. The temporary setting, if present,
is marked with a check mark instead of a bullet point, and has precedence over
the configured setting. The temporary setting will be discarded when another
non-temporary setting is selected, or the program exits.

Hold Control to immediately enter full-screen mode using your selection.
If you are already full-screen, the program will re-enter it, with some
slight delays.

It is permissible to use both qualifier keys to immediately enter full-screen
mode using a temporarily selected preference.

 By Window

This is the default preference. It enters full-screen mode on whichever monitor
the main window is currently on. If the main window spans multiple displays
(NOT recommended), it will pick the one with greatest area of intersection
with the window, unless you double-clicked the main part of the window,
in which case it will use whichever screen the cursor was on at the time.

 By Cursor

This mode dynamically picks a display based on the mouse cursor location
at the time when full-screen mode is initiated. This is potentially confusing,
as most people aren't omniscient when it comes to the location of their cursor.
The problem is exacerbated when monitors are turned off: the program window can
seemingly disappear for no obvious reason.

However, this option enables one to rapidly select a full-screen display
with a mere flick of the wrist, which is highly convenient.

Note that this setting is only useful if you use the keyboard to enter
full-screen mode; double-clicking the window necessarily puts the cursor
on the same display as the window, which produces the same behavior as
the default setting: By Window.

 Primary

This preference always uses the primary display, which is typically where
most of the action on your computer takes place.

 Secondary

This option is ideal if you only have two displays, and you prefer not to use
the primary one. However, it might not select your desired screen if you have
more than two. In such a case, you should use one of the following settings.

 By Ordinal

At the bottom of the menu, up to 10 items will be listed, each representing
a qualifying monitor. (Displays will be omitted if their resolution is too low.)
You can use these menu items to select a screen by its assigned number.

Since you might not know the number assigned to each of your displays, in order
to differentiate them, the status bar will show the size and origin coordinates.
Note that the primary display is not necessarily the first monitor, although it
typically is.

This is the least reliable method of configuring a monitor selection,
because the number assigned by the OS can change if you add/remove/change
video connections. It is even possible to change the order through software,
via a driver control panel, for example.

However, this preference can be useful if you regularly change the virtual
position of your displays. As long as the ordinal hasn't changed, the same
screen will continue to be used regardless of its relative position.

If the specified display number is no longer valid, the primary will be used.

 By Relative Position

This method is more predictable than the previous one. Even if the connections
or ordering change, the same display will consistently be selected as long as
its relative position remains the same.

When entering full-screen, the virtual desktop will be searched for a screen
situated right/left/above/below the primary. Several algorithms are used.

Because one of the algorithms is based on distance, it may end up selecting
an unexpected monitor. For example, a display situated to the side of the
primary could qualify as a top or bottom monitor if it juts out vertically
to a sufficient extent, with no other display above/below the primary.

The primary will be used if heuristics fail to locate a suitable display.





 Startup Options Reference
------------------------------------------------------------------------

The Window menu has a submenu for options controlling the main window's
location and attributes when the program starts.

Most of the items on the menu are for specifying which monitor the window
will start on. The majority of them will be inactive on single-display
systems. Consult the earlier full-screen portion of this document for
details on some of these preferences; only the window-specific items
will be documented below.

In addition to the window location, there are submenus for specifying the
state of the window bars, and also whether to start full-screen or not.
As noted below, these preferences will be unavailable in certain modes.

 Classic Resume

This menu items reflects the state of the Tools > Options > Resume > Window
setting. If enabled, the window position, full-screen state, and the state
of each of the three bars (caption/title, menu, and status) will be recorded
in the configuration file, and subsequently restored the next time the program
is started.

Note that, if the configuration file cannot be written to (e.g. because it is
marked read-only at the file system level) then nothing will be saved; in such
a case, whatever values were previously successfully written to the file will
be used instead. (Such behavior is not unique for this particular preference.)

If you prefer finer control over the bars and/or full-screen startup state,
you should first select whichever non-classic option best suits your preference
for the initial window state - they all enable the submenus granting greater
control of the other attributes.

You can toggle this setting via the Window menu or the Options dialog (Alt-O).
Turning it off via the dialog is equivalent to selecting Classic Default below.

 Classic Default

This setting is the opposite of the previous: on startup, the defaults will be
used for all of the applicable settings mentioned above.

These first two options are labeled "classic" because they emulate the original
behavior of this program. All of the remaining preferences enable finer control
over the state of the various window attributes on startup.

Therefore, for consistency, if either of the "classic" preferences are selected,
some of the other options will be disabled: these are all-or-nothing settings.

 Previous Location

This option attempts to keep the window in the same location as it was when you
last quit the program. It does so by saving the window's previous coordinates.

As noted earlier, resuming only works to the extent that the configuration file
is writable; else it will use whatever coordinates were last successfully saved.
In any case, the coordinates will be vetted to ensure that the window will be
at least partially visible; otherwise it will be relocated.

If you're thinking that you could save the coordinates once, then make the
configuration file read-only, in order to to keep the window starting location
consistent by leveraging the behavior described just above, you don't have to!
Instead, you can just use the Fixed Location preference, as described below.

 Previous Display

This operates the same as the above except that it always repositions the
window to the center of the screen, instead of using the exact location.

 Fixed Location

Perhaps you sometimes move the window, maybe inadvertently, but would prefer it
to always start at a particular location. If so, this preference should fulfill
your desire.

It is functionally the same as the Previous Location setting except that it
only updates the preserved window coordinates when you explicitly order it to,
by selecting or re-selecting the corresponding menu item. Whenever you do so,
the current window coordinates are stored. When the program exits, the stored
coordinates will be written to the configuration file, even if you moved the
window in the intervening period. These coordinates will be used the next time
the program is started, and every time thereafter, until and unless you choose
a different start-up preference.

 Defer to OS

Not recommended. Your OS will decide the initial placement of the window,
which will then be centered on whichever screen it ends up on.

The problem with this setting is that it behaves inconsistently depending on
how the program was launched. For example, sometimes it takes the mouse cursor
into account, sometimes it doesn't. The only reason this option even exists
is for dogged support of previous modalities - if you want this program to
behave exactly like it used to, then technically you should be using this
setting, even though one of the others will probably satisfy you, with the
added benefit of behaving consistently.

Note that you do NOT need to use this mode in order to start the program
minimized/maximized using customized shortcuts. (Nobody actually does that,
but it is supported.)

If basing the window location on the mouse cursor sounds intriguing,
consider using the setting below instead.

 Same as Cursor

As mentioned in the corresponding preference listed in the full-screen display
section of this manual, dynamically selecting a display using the mouse cursor
location has the potential to be confusing, particularly if one or more screens
happen to be turned off.

However, OS vendors have been working hard to hamstring keyboard users
in recent years, so in all likelihood, you only ever launch the program
by clicking on an icon (or possibly by dragging a file onto an icon).
In such a case, this setting increases the likelihood that the window
will start on the same display as the icon you interacted with. (It is
possible to move the mouse after launching the program, so there is no
guarantee that it will still be on the same display at the time when the
window finally materializes.)

Therefore, this setting tends to yield intuitive results, except when
it doesn't. But as long as you understand how it works, and its potential
pitfalls, it is an attractive option. Even keyboard users may find it
convenient for dynamically selecting a monitor. In certain situations,
it can save you the hassle of dragging the window.

 Centered on a Display

The remaining items are preferences for selecting which display to center
the window on. They are described in the earlier full-screen display section.
The only difference is that, in this menu, they control which monitor the
window starts on. In all such cases, the window will start centered on the
selected display.

Some of these options will be disabled if you only have one qualifying display
connected to your computer. Also note that, if you selected a monitor ordinally,
and it is no longer present, the primary will be used instead.

The Primary preference is an excellent choice, even if you do not have
multiple displays. It ensures that the window always starts centered,
and, unlike Classic Default, you have full control over the other options,
which are described in more detail below.

 Other Startup Settings

Unless you selected one of the classic options, you can configure each of the
three bars (caption/title, menu, and status) independently, along with the
full-screen startup state.

You have three options for each: start enabled, start disabled, or use the
previously saved setting (i.e. "resume"). (In the case of resuming the previous
state, there are caveats, described in more detail earlier, about how the
configuration file needs to be writable for them to function as described.)

As an example, suppose you sometimes turn off the status bar by double-clicking
its left side, but normally you prefer it to be enabled. Its default setting is
to always start enabled, so as long as you aren't using the Classic Resume
feature, you get the desired behavior without having to configure anything.

Now consider the expert keyboard user who knows how open menus using the Alt
and/or Apps keys. He could configure the menu bar to always start hidden,
reclaiming a small (but potentially crucial) amount of vertical space.

It is also possible to set the program to always start in full-screen mode,
or to resume the previous fullscreen/window state. The specific full-screen
monitor selected will depend on other settings, however, although there may
be some interaction with the window startup settings if the full-screen
preference depends on the current window location. (Even when starting
full-screen, the initial window location is first determined as normal.)

If that doesn't make sense, then just remember to check the View menu's
Full Screen Display submenu if the program isn't starting full-screen
on the expected monitor.





 Command Reference
------------------------------------------------------------------------

Reset:

Simulates pressing the X68000 button labeled RESET.

This will not clear out the contents of RAM, although the IPL will still
initialize its work area. Properly written software will be unaffected
by the contents of uninitialized RAM.

Historically, XM6 would sometimes reset the VM in response to user actions,
such as simultaneously inserting two floppy disks. Now these resets only
occur if the setting Options > Misc > Auto Reset is enabled.

If you inadvertently reset the system, use the Undo command.


Reset and Clear:

Similar to the above but also clears out most forms of RAM. This tends
to reduce graphical glitches and inconsistent behavior of VM software.

Periodically cleaning the VM memory in this way also improves the
compressibility of state files.

The only potential downside is that it also erases SRAM (which can
harbor viruses or bad settings which can render the VM unable to
boot properly). However, most users won't have anything important
saved in SRAM. If you are unsure, you can always create a state file
beforehand; SRAM is saved/loaded along with the rest of the VM state
when using state files. Another option is mark the SRAM.DAT file as
read-only (see the Tools > SRAM menu) so that any changes to SRAM
will not be saved on exit. (However, in such a case, any previously
saved bad SRAM settings will return the next time you start XM6.)


Interrupt:

Simulates pressing the X68000 button labeled INTERRUPT, which generates
a non-maskable interrupt (NMI). The effects will depend on the software,
but the usual intent is for it to halt the currently running program.
Games that are known to react otherwise are documented in the notes file.

The menu item will be marked if a non-trivial NMI handler is installed.
This means generating an NMI may (or may not) do something interesting.

If the NMI results in an unwanted effect, use the Undo command.


Power Switch:

Simulates toggling the X68000 power switch. This generates an interrupt.

It will take a few seconds for the system to power down. If you are
quick, you can flip the switch back on in the meantime. There might
not even be any side effects if the default handler is being used,
which gives the user a brief grace period before starting. However,
even if the switch is toggled back on quickly, interrupts will still
have been masked for several seconds, which could cause problems.

If you accidentally flipped the power switch, use the Undo command.

If the system crashed with interrupts disabled/masked then the X68000
software will not be able to power down the system. In this case you
need to perform a reset in order for it to power down, interestingly.

Other things can block the power-down sequence as well, such as error
dialogs (e.g. Abort, Retry, Ignore).


Undo:

As a safety feature, an in-memory copy of the VM state will be made
before resetting, regardless of whether or not the reset was initiated
directly by the user.

The Undo menu command can be used to reload this state copy.
A dialog will appear, providing more details along with an
opportunity to cancel.

In addition to resets, this backstop also applies to a few other events:
turning the virtual power switch off or pressing the Interrupt button.

 Warning: This feature is only intended to revert accidental losses.
 Do not abuse it for other purposes; the undo command only persists
 for a few minutes at most. (If you need more time, pause the emulator.)


Refresh:

This command redraws all windows, including the X68000 screen.
It is unlikely to do anything useful absent a bug in XM6.

If emulation is paused/halted then the redrawn screen may
suddenly look different. For example, sprites might disappear,
or the background might scroll once. This is because a refresh,
by convention, renders the screen all at once based on the
current static state of the VM, whereas normal rendering takes
place incrementally throughout the frame and only updates when
everything is finished. Therefore, you should not consider a
refreshed view to be reliable. If it looks like refreshing
is sometimes revealing the next frame, it is, in a sense,
but it is only a preview. Any further refreshes while paused
will not change anything.

Loading a paused state file initiates a refresh so that
at least something can be shown while waiting for the
user to unpause the VM. As explained above, the result
might be inaccurate sometimes.


Adjust Time:

X68000 systems include a real-time clock (RTC). Although it will be set
to the current time whenever you start the emulator or turn on the VM,
it is otherwise independent. When you load a state file, the previous
state of the RTC will also be loaded, which will undoubtedly not match
the current time. Fast-forwarding can also cause the RTC to rapidly go
out-of-sync with reality. This is not necessarily a bad thing; certain
games and other software sometimes behave differently depending on the
RTC's time of day, day of the week, or even the calendar date, so it
is beneficial to emulate the RTC independently instead of tethering it
to your computer's clock.

If you wish to set the RTC to the current time, select Adjust Time
under the Tools menu. If you hold Shift, the RTC window will open.
You can then manually adjust the date/time by double-clicking some
of the fields. Invalid entries are only quasi-supported at this time,
because the emulation of such values is incomplete.





 Debugging Command Reference
------------------------------------------------------------------------

Trace:

Executes the next instruction. Similar to "step into" commands,
in debugger parlance. Be warned that the effects are not necessarily
identical to how the VM would normally behave, due to the very short
execution cycle. There are other side effects as well, such as cheats
not activating.


Step Over:

Either executes the next instruction or runs to a special breakpoint
after it, depending on what instruction it is. It is used for skipping
over subroutine calls and similar operations, which are listed below.

    BSR CHK DOS FPACK IOCS JSR TRAP TRAPV


Skip Ahead:

Runs to a special breakpoint at the next point of interest, which
includes the instructions listed in the previous paragraph as well
as any line with a breakpoint, branch, or return statement. If the
next instruction to be executed is a subroutine call or similar
statement, this command will run to the next line just like the
Step Over command would. In the unlikely event nothing "of interest"
can be found nearby, it will run a set number of instructions.


Run to Next:

Attempts to run to a special breakpoint set on the next instruction.
This is intended to be used to skip over certain looping instructions.
It is recommended that you only use this command when you know for
certain that the current instruction is the only one that can terminate
the loop; otherwise you risk losing control.


Run to End:

Attempts to run to the end of the current subroutine. It executes
instructions until it finds a return operation (any kind) coincident
with the following criteria:

- The Supervisor Mode bit must be in the same state as when this
  command was invoked.

- The Stack Pointer must be no less than when this command was invoked.

This algorithm won't work in every situation but should be adequate.
If the subroutine never returns, you can abort the operation by halting
execution (Alt-F12).

If successful, execution will end at the RTS/RTE/RTR. To finish
"stepping out", simply perform a single Trace command (F11).


Step Out:

Same as Run to End except that it executes the return instruction
for you as well. If an exception occurs at the return instruction,
you won't end up in the correct place after all, so be mindful of
this possibility if you end up somewhere unexpected.


RAM Insert:

Loads a file directly into the X68000's main memory. You will be
asked for the destination address, which must be less than the amount
of memory installed in the X68000. Typically this will be $200000,
but it could be as high as $C00000 depending on the configuration.


RAM Dump:

Saves the entire contents of the X68000's main memory into a file.


Memory Dump:

Saves a range of data from anywhere in the address space to a file.
Unlike the RAM Dump command, this function can read from VRAM and other
addresses above $C00000 but is much slower because it has to interface
with various memory handlers.

You will be asked for two addresses. Together, these values bound the
range to be saved. The first is inclusive/closed, the second is
exclusive/open. Only the lower 24 bits will be used, but if the latter
value is zero, it will be treated as $1000000 (i.e. the top of the
address space.)


CPU State Log:

This will disassemble the current instruction and output the most
useful CPU registers to a file every time an instruction is executed.
It will stop automatically once it writes about 20 MB. You can also
manually halt it by selecting the menu item again.

You can easily control what gets logged by using the disassembler
window, breakpoints, execution commands, etc.; the logger will remain
active while you step through the code or run between breakpoints.


Save Disassembly:

Disassembles instructions with a few formatting niceties. You will
be asked first for a file name and then the end address (inclusive)
which will default to the end of the current "page" (purely an artifact
of the disassembly window architecture; the 68000 uses a flat addressing
scheme). The start address is taken from the current view of the
corresponding disassembly window.

You can also copy approximately 4kB worth of disassembled instructions
to the clipboard by pressing C / Ctrl-C in an active disassembly window.






 Memory Search
------------------------------------------------------------------------

Each open memory window can launch a non-modal dialog with the ability
to search the X68000 main memory. Pop-up-style windows are not required.

Both forward and backward search directions are allowed; simply press
the corresponding button. A small combo box controls the address where
the search will start from (which is +/- one byte from that address
depending on the direction; i.e. searching from address X will start
at X + 1 for forward searches or X - 1 for backwards searches.)
Searches will wrap around until all RAM has been scanned.

Holding Shift while activating one of the search buttons will reverse
the search direction. Holding Control will cause the dialog to close
after the search is attempted. Searches can be repeated after the 
dialog closes by pressing (Shift) F3, albeit the corresponding memory
window must have keyboard focus and be pop-up style.

The starting address is preloaded with whatever is on top of the
parent memory window. Every time a match is found, the corresponding
address will be added to the list box, which will also be preloaded
with address zero for your convenience. The contents of the list box
will not persist after the search dialog is closed.

The starting address determines the area of memory to be searched.
Normally one will only want to search main RAM, but if the address
is within certain allowed ranges then the corresponding type of
RAM/ROM will be scanned instead.

For example, if the address is between E00000 and E80000 (exclusive)
then TVRAM (and only TVRAM) will be searched. This feature notably
excludes GVRAM and the first $20 bytes of the external SCSI area.

The "Align" check box can be used to constrain the set of addresses
that can qualify as matches, potentially reducing false positives.
When active, aligned searches require that an odd number of bytes
can only start on an odd address and vice versa. Alignment only
applies to search sequences ranging from one to four bytes in size.

For example, when alignment is enforced, 16-bit and 32-bit quantities
will only match when found at an even address; values that span words
will be filtered out, which is normally desired since the processor
requires such quantities to be word-aligned. Searching for a 24-bit
address with the alignment option will only report odd address such
that the full 32-bit address (MSB unused) will be properly aligned.

The dialog contains an edit control where you enter the search string.
It will treat the input as either hexadecimal bytes or a raw character
string (case-sensitive). Alternatively, a single decimal value can also
be entered by using a special prefix as described below.

The following are tolerated in hexadecimal strings:

 white space, commas, dollar signs, and the sequences "0x" and "0X"

All hexadecimal digits are isolated and a leading zero is added if
the total number is odd. The digits are then converted to binary to be
used in the search routine.

Examples of valid hexadecimal sequences:

 0
 $b
 Af
 123456789ABCDEFabcdef$$$,0x
 0x00, 0x01, 0x02
 $d $f0 $3
 0x10x20x3

Note that the last two examples may not give you the expected results.
They correspond to the sequences $DF03 and $123.

If any non-hexadecimal character other than those above are encountered
while parsing the input then the data will be treated as a string of
case-sensitive characters. This includes JASCII / "wide" hex digits.
The sole exception is if the decimal prefix (#) is used.

A decimal number can be searched for by prefixing the number with
the '#' character. An optional minus sign can appear on either side
of the prefix, and commas are tolerated between digits. The decimal
value will be converted to a byte sequence; it will be padded to be
at least two bytes since single-byte decimal sequences are not very
practical. If the value exceeds 10 digits or unexpected characters
are found, then the input will be treated as a string.

There are some sequences which are ambiguous. For examples, searching
for "BAD AD" (without the quotes) will perform a hexadecimal search,
which may not be what you intended.

Examples of common English words that are also hexadecimal numbers:

 a accede acceded ace aced ad add added
 bad bade be bead beaded bed bedded bee beef beefed
 cad cab cafe cede ceded
 dab dabbed dad dead deaf deed deeded
 ebb ebbed efface effaced
 fa fab face faced fad fade faded fed fee feed

You can force the input to be treated as raw characters by prefixing
the search with a quote mark (single or double), which will be stripped
out for the actual search, along with an optional trailing quote mark.
Quote marks in other places will be used in the search. There are a few
other oddities regarding quote marks; in the unlikely event you want to
find one occurrence of a quote mark and nothing else, you can enter
one, two, or three of them in a row and the result will be the same.

Examples of valid character sequences:

 asdf
 'DEAD
 "aaaa
 "Boo"
 freerf"333~+
 "
 ''
 """

The dialog will also accept most Japanese characters, but they must be
Shift-JIS encoded in the ANSI version of the program and Unicode encoded
in the Unicode version.

Be aware that you can still only search for Shift-JIS characters
(or ASCII) even in the Unicode version. If the search string cannot
be fully converted to Shift-JIS, the search will fail. It is not
likely that any extant X68000 software uses Unicode, so the conversion
is actually beneficial; Unicode input would be useless otherwise.

Depending on your system settings, the Shift-JIS characters might not
appear properly in the ANSI version, but as long as they are bona fide
Shift-JIS then the search will succeed. Question marks usually mean that
you pasted Unicode into the ANSI version and it couldn't be converted.

If XM6 detects that you have the Japanese language installed on your
system, a Japanese font will be selected for the edit control at runtime
so that you can see Japanese characters in the search dialog, even in
the ANSI version.

Unicode input does not work in the ANSI version (it will be converted
to question marks before XM6 gets it). Chances are your IME won't emit
the Shift-JIS format needed by the ANSI version unless your locale is
set to Japanese.

If you need more powerful search functions you can use one of the
other commands to export memory to a file and use external tools on it.

A message may appear in the status bar at the bottom of the frame window
to indicate that the search failed, that a repeated search failed, or
that the search wrapped around.

It is recommended that you halt emulation prior to performing a search,
but it is not required. It can happen that a matching address is found
but the value gets changed soon afterwards, leading to confusion when
the memory window seems to jump to an address containing the wrong value.





 Dynamic Memory Search (DMS)
--------------------------------------------------------------------------------

This feature is integrated into the Memory Window. You can switch back and forth
between this mode and the standard memory view at any time. Whereas the usual
mode shows every value stored at an arbitrary range of addresses, the DMS mode
only shows RAM addresses that have met your criteria. Thus you can reduce the
displayed addresses down to those you are interested. This is most useful for
cheating and similar "hacking" purposes.

Note that pop-up-style subwindows must be enabled in order to use this feature
because the interface is almost entirely keyboard drive.

Initially, every RAM address will be displayed and the X68000 RAM contents will
be copied into a buffer. As you issue commands, memory locations will be hidden.
Typically one would continue issuing commands at various points until one or
more addresses of interest are found.

The most useful commands compare the current RAM values with their earlier
state as stored in the buffer. In this way, one can constrain the address set
to those that have increased, decreased, changed, or stayed the same. After
any such commands, the buffer will be updated automatically, although this
feature can be inhibited. The buffer can also be updated manually at any time.

Be aware that there are two sets of addresses: one for byte-sized values and
one for word-sized values, although only one set will be displayed at a time.
Since one typically does not know the size of the value of interest in advance,
DMS operates on both sizes simultaneously. This eliminates the need to guess
the correct size at the start. The subwindow title bar displays the number
of extant locations for both sizes.


 Dynamic Memory Search Commands

Please see the key reference or the integrated help to learn about all the
available commands and the keys that activate them. This section only documents
a few commands that need more detailed descriptions.

Run after Search

Disabled by default, this feature causes emulation to resume automatically
after any relative search is issued. Absolute value searches are not affected.

Update

This command copies the current values of the X68000 RAM into a buffer that
is used for relative comparisons (i.e. comparing against the previous value).
Normally the buffer is copied automatically after such searches, but you can
manually update the previous values at any time with this operation. There is
also a command to toggle the aforementioned automatic updates.

Undo

Only one undo level is stored. Undoing a second time will act like a 'redo'
operation. The RAM copy used for relative comparisons is not covered by the
undo operation so you may want to use the 'update' command after undoing to
avoid getting confused.

Units

You can switch the units between byte and word (8 and 16 bits) at any time.
All commands operate on both sets of addresses regardless of which one is
currently being displayed. The units will automatically switch if one set
is fully depleted.

Viewing Modes

There are two modes: full and compact. The former displays one memory location
per line along with the previous value in parentheses. In Byte Mode it may
also display "B/W" indicating that the address in question also exists in the
word-sized set.

Compact mode operates similarly to the standard memory viewer with 16 bytes
displayed per line. When only one location is extant from a 16-byte range,
the line will be formatted with the exact address shown on the left.


 Dynamic Memory Search Topics

Input Radix

When comparing against a specific value, the input will be interpreted as either
decimal or hexadecimal depending on several heuristics.

If the input is unambiguously hexadecimal then it will be treated as base 16.
Prefixes will also set the radix: use '#' for base 10, '$' or '0x' for base 16.
Otherwise the current default radix will be used.

The default radix, represented by a symbol, is displayed in the title bar.

Note that addresses always default to base 16, although the '#' prefix can still
be used to force the input to be interpreted as decimal.

Signed versus Unsigned

Owing to the miracle of two's-complement arithmetic, most mathematical
operations can be performed transparently without explicitly defining
the signedness of the operands. Problems can arise when comparing two
values, however.

In situations where two values cannot be compared unambiguously without knowing
whether they are signed or unsigned (i.e. the sign bits differ) then they will
be skipped. In other words, the address being tested will remain viable until
another search is performed, at which point they will be reevaluated based on
the new criterion.

This is done because the user is unlikely to know for certain how to interpret
the value being sought. Although most values in computing tend to stay positive,
it is not expected to be burdensome to support both sign bit interpretations.
Indeed, the signedness of a variable is basically meaningless as long as the
range of values it can possibly contain is sufficiently constrained.

In practice, this rule only applies to the increased/decreased criteria.

Byte versus Word

It is fairly common to find a byte-sized candidate at an odd address where the
word at the corresponding even address also met all of one's search criteria.
(Typically this happens when the even byte stays zero, although there is a small
possibility that two contiguous bytes with different purposes just happened to
follow the same criteria when interpreted as a word quantity.)

When faced with such an ambiguity, one can often determine the correct size
experimentally by modifying the even byte and observing the results. However,
if this is too arduous, it is generally safer to treat it as the smaller size,
even though this will be formally incorrect much of the time.

Misaligned Words

Misaligned words are not supported by the early 680x0 processors so they
are not likely to be used for storing variables of interest on the X68000.
Such usage would be more plausible in poorly programmed X68030 software,
but such programs would not be backwards compatible with the X68000 and
therefore would not run on this emulator anyway.

Long Words

32-bit values are not supported because they are rarely needed, thus making
the additional memory storage and code complexity difficult to justify.
Their lack of natural alignment (i.e. they only require 16-bit alignment)
also makes the search implementation significantly more complicated.

However, it is still possible to find the lower half of a 32-bit variable
if you know the exact value: when you input a quantity that cannot fit within
16 bits, only the lowest 16 bits will be used. Therefore you do not have to do
any numerical conversion or bit masking yourself. You won't be able to tell
if the upper bits at the preceding address are correct, however.

The 32-bit view is still available in DMS mode; the viewer will simply
display all RAM addresses without any exclusions, affording the user
an  opportunity to examine certain values in context.

Other Quantities

There is no way to directly track changes in bit fields, individual bits,
or any other logical arrangement of memory other than bytes and aligned words.

Memory Watches

You can "watch" specific memory addresses by first removing all addresses
and then manually adding the ones you are interested in. Another way to do
this is to constrain the addresses down to a single location (or a contiguous 
range of addresses) and manually add any additional locations if so desired.

TVRAM

Games sometimes use TVRAM to store variables of interest. By default, DMS only
searches RAM; however, you can switch the search region between RAM and TVRAM
using the appropriate command. This should normally only be done if you are
unable to find what you are looking for in RAM. Any previous search results
will be discarded when changing the search region.

In this mode, only TVRAM will be searched. You can specify addresses in their
canonical form ($E00000 - $E7FFFF) or use the range $000000 - $7FFFF instead.
Note that in certain cases you may see the same values repeated at intervals
of $20000. This is due to the way the hardware is sometimes configured to work.
Typically the variable will only be read from one of the duplicate addresses.





 Cheating
------------------------------------------------------------------------

Once you've found a prospective address using Dynamic Memory Search,
you can add a cheat directly by holding Control and double-clicking
the address. This will open a dialog with certain fields populated.
You can also add a cheat manually through the menu interface.


 Interface

The cheating subsystem is largely interfaced through the menus,
most of which are self-explanatory or otherwise intuitive.

The Master Enable flag must be set in order for cheats to take effect.
It will be cleared during a reset if any cheats are enabled. This is
done for safety reasons.

If you do not provide a description for a cheat, the address and value
will be displayed instead. Otherwise, you can view this information
in the status bar. For the most common cheat types, the value will be
displayed after the description.

When manually entering an address into the cheat dialog, it is possible
to simultaneously set the size by using a suffix. E.g. append .B for
byte-sized cheats. 'W' and 'L' specify word and long-word respectively.

The Accept button adds the cheat and closes the dialog. If editing a cheat,
by selecting an existing cheat while holding Control for example, the cheat
will be updated instead of added.

The "Add as New" button always adds a new cheat when pressed. It does not
close the dialog, in case the user wishes to add a series of similar cheats.
If the button is pressed multiple times, and the cheat parameters have not
changed in the interval, then the dialog will be closed instead. In effect,
double-clicking the button will add a new cheat and close the dialog.


 Cheat Types

Constant Value

The default type simply writes a constant value to the specified address.

Automatic Value

This type does not accept a value - only an address. The value to be used
will be read from the specified address whenever the cheat becomes enabled.
In other words, when activated, this cheat maintains the value of a variable.

Relative Value

The value will be added to the memory variable whenever this cheat is enabled.
This type is necessarily always one-shot, which effectively means that it will
only activate on demand. It is useful for modifying coordinates or similar
variables where only the desired delta can be known ahead of time.

Logical AND/OR/EOR

A logical operation will be performed on the value. This can be used to
set or clear individual bits without affecting the rest of the variable.
The EOR (Exclusive OR) type can only be one-shot, to avoid chaotic effects.

Memory Copy

This type accepts two address: a source and a destination. The source
address will be read and its value copied to the destination address.


 Modifiers

One-shot

If set, this flag causes the cheat to disable itself after being applied.

Specify

A dialog will appear whenever the cheat becomes enabled, thereby providing the
user an opportunity to modify the value. This is more practical for one-shot
cheats when the desired value will change periodically.

The default value for the dialog will be whatever the previous value was unless
the cheat type is Automatic Value in which case you will see the value of the
variable you are modifying. (Be aware that the variable could change at any time
if the VM is still running, however.)


 Caveats

Cheat codes can cause crashes or other undesirable effects if they are enabled
at the wrong time, such as during startup. Leaving cheats enabled when switching
games is also liable to cause serious problems. Different game modes, such as
an ending sequence, may also be susceptible.

The address of a particular variable may change depending on the version
of the game or the settings in use (such as the amount of X68000 RAM).
HDD installed games very often run at different addresses.

Cheats will not be applied when emulation is paused.
Cheats may or may not be applied during debug operations.

Be careful about setting a value too close to the limits of its natural
excursion range. Otherwise it might roll over/under when the game tries
to modify it.

Cheats applied to TVRAM and SRAM will be written directly and unchanged.
This may be different than what would occur if a real X68000 program
were attempting to write to the same address at that particular time.

At this time, there is no direct way to save the cheats you have created.
However, they can be exported to or imported from the clipboard using
the menu interface. After exporting, paste them into a text file for
later retrieval. To restore your cheats, open your text file and copy
them back onto the clipboard, then import them into XM6 using the menu.

Imported cheats are not enabled by default, because doing so can be harmful,
but you can force all cheats to be enabled by holding Shift when importing.

By default, when importing cheats, existing cheats will not be deleted
although they may be replaced by a cheat that is broadly the same but
has a different description or flags. However, if Control is depressed
then the import function will purge all existing cheats the moment it
finds a valid cheat on the clipboard. You can take advantage of this
feature to easily clean up the descriptions or rearrange cheats.





 Unicode and MBCS Editions
------------------------------------------------------------------------

(In this context, the term "ANSI" is a misnomer referring to the local
code page. Said term is also used to refer to the non-Unicode version
of this program, more properly called the MBCS version.)

There are two versions of the main program: MBCS ("ANSI") and Unicode.
The Unicode edition is recommended for most users, now that most of
the compatibility limitations have been overcome.

 NOTE: This section only covers the character encoding differences.
 Another major difference is that the MBCS version still uses the
 old graphics engine, which is much less accurate but sometimes faster.

The principal advantage of the Unicode version is that it can handle any
valid Unicode characters in file names and paths. The MBCS version can
only read/write files where the entire path can be converted into the
local code page.

The MBCS version cannot decode UTF-8 (Unicode) file names in archives.

Both editions can read state files created in the other format,
although the MBCS version will not be able to use any paths that
are not compatible with the local code page. State files created
by the original XM6 are mostly forwards compatible, but only the
MBCS edition creates state files that the original can still read.
(The original XM6 is very outdated now, so backwards compatibility
is not too useful anymore.)

Regarding the text-based configuration file (XM6.ini), both editions
will transparently convert the other format. In some cases the program
will attempt to rename the file before replacing it. Be aware that the
MBCS version won't correctly convert paths that contain certain symbols.





 User Interface Language
------------------------------------------------------------------------

By default the interface will be in English unless the OS is configured
to present in Japanese.

Changing the executable name to XM6J or XM6E will force the language
to be Japanese or English respectively. Please be aware that the results
will not be identical as compared to running on a language-specific OS,
for unknown reasons.

The Unicode version is much more likely to work in this respect.





 Delta Files for Floppy Disk Images
------------------------------------------------------------------------

It is possible to store modified floppy disk sectors in a separate file,
known as a delta file. This feature enables the preservation of changes
to non-writable images, such as those contained within archives. It can
also be used, if some prior preparation is performed, to redirect the
changes to an otherwise writable image, allowing it to remain intact
while still permitting updates, such as saving one's progress in a game.

If XM6 is unable to write modified sectors back to the original image,
for whatever reason, the changes will remain pending until the disk is
ejected. In the past, such changes would simply be discarded, but with
the advent of delta file support, it is now possible to record those
changes in a separate file to be reloaded the next time the disk image
is inserted. By default, this all occurs transparently.

The technical details are expounded below, followed by an explanation
of the user interface.


 How Delta Files Are Used

Although delta files were designed to support incremental updates,
at this time they are only being written out, in entirety, after the
disk has been ejected, and only if changes were made - existing delta
files will not be rewritten unnecessarily, nor will superfluous empty
files be created.

Similarly, delta files are only loaded when their corresponding disk
image is first inserted, and only if delta file support is enabled.

Delta files are stored alongside the original image or archive and have
the same file name as the corresponding image except with an extension
of "dlt" instead of e.g. "xdf". Deleting or renaming them will revert
the changes the next time the image is loaded. You can also mark them
as read-only to prevent further modification.

Although reverting changes is simple enough, merging a delta file into
an image is not supported and could only be accomplished under certain
circumstances anyway. If you wish to do this, a workaround is to copy
the disk to another image that is capable of being modified.

Delta files are not supported for a small number of exotic image formats.

Delta files within archives are ignored.

Delta data could be stored in state files, in order to ensure that the
state of the disk corresponds to the rest of the saved VM state, but in
practice this is rarely necessary because most games keep all their saved
data in RAM at all times. Furthermore, you would run the risk of losing
newer disk data if you hadn't made a recent state file and then loaded
an older state file.


 When Delta Files Are Used

As noted earlier, changes are only written to delta files if they were
unable to be saved into the disk image file itself. This can happen for
two basic reasons, described below.

The first reason images cannot be updated is because the format itself
does not support it. Disk images contained within archives are the most
common case. Files composited into disks on-the-fly are another example.
Some copy protected images are also required to be immutable.

Regardless of the specifics, changes made to disk images of this class
can only be preserved if they are stored in delta files.

The second case is when the OS prohibits updates to an image file that
would otherwise be modifiable.

The most common example of this type would be when an image file is set
as read-only at the file system level, whereupon the OS will block any
writes to it. XM6 will usually detect this and set the write-protect
flag* so that X68000 software will not be able to enact any changes.

* Some floppy disks have a notch or tab that the disk drive can detect
  in order to determine writability. This flag emulates that feature.
  If an image is not read-only, you can toggle the flag via the menu.

However, it is sometimes possible to circumvent or override said
write protection: one fully supported method involves putting "[W]"
into the disk's file name, which will force it to be writable even
if it is marked read-only at the file system level.

The Delta Files submenu has several commands that can also be used
to (re)open an image as writable. This override only lasts until
the disk is ejected; however, if a delta file was created during
that time period, the image will again be set as writable upon
loading said delta file the next time the image is inserted.

Finally, read-only images that are listed in the internal database
as needing to be writable will be overridden automatically unless
the "[R]" flag is found in the file name.

 Note that the Write-Protect option listed in the floppy drive menus
 controls the virtual floppy drive's write protection. If the drive
 sees the disk as being write-protected then X68000 software will be
 unable to modify the disk; such attempted modifications will NOT be
 accumulated as pending changes - only writes that succeeded at the
 VM level are eligible to be stored in delta files, and even then
 only if the image file itself could not be updated.

In summary, delta files are only used when valid changes to a disk
would otherwise be lost.

Regarding frequency, the majority of X68000 disks do not get modified
during normal operation, so delta files will not appear highly often.
You might never even see one if you do not use archives or read-only
images much.

If you wish to forcibly redirect changes into a delta file for a given
image, append "[W]" to the file name and then mark the file as read-only
using one of the OS interfaces (e.g. the Properties dialog or ATTRIB +R).

You can also force delta files to be created, with some caveats,
by using the Delta Files submenu as described above.


 User Interface for Delta Files

Delta files are controlled through the menu interface under the drive
menus. Each floppy drive menu has a Delta Files submenu: the upper part
of the menu contains drive-specific items and the lower part contains
configuration items of general applicability.

If a disk is inserted into the corresponding drive, and delta file
support is active, then you will be able to select the action to take
upon disk ejection: Ask, Keep, Discard, or Delete. The default action
can be selected in the configuration. You can change the action at
any time before the disk is ejected.

If there are no pending changes (i.e. any changes were successfully
written back to the image file) at the time the disk is ejected then
no action will be taken, unless Delete was selected, which wipes out
an existing delta file.

Because it can be difficult to predict whether a delta file will even
be needed, one is typically better off just configuring the defaults,
as described below, rather than manually adjusting the action.

 Ask

If this action is selected then a message box will appear when the disk
image is ejected asking the user if they wish to save the changes.
Selecting "No" will discard any changes made during the current session.
Selecting "Yes" will keep the changes. See below for more details.

Be aware that the message box, being "modal", will halt the VM thread
until it is dismissed.

 Keep

If this action is selected then the delta file will be created/updated
as necessary when the disk is ejected.

If there are no pending changes upon ejection, nothing will happen.

 Discard

If this action is selected then any pending changes will be discarded
when the disk is ejected. This is how XM6 operated historically.

When discarding, a delta file will not be created, and an existing
delta file will not be updated, if present.

 Delete

If this action is selected then any pending changes will be discarded
and the delta file itself will be deleted when the disk is ejected.

This action cannot be selected if a delta file was not loaded at the
time the image was inserted into the virtual drive.

You can use this feature to revert changes: first insert an image that
has a corresponding delta file, then select this option through the menu
interface, then eject the image. The delta file will then be deleted,
if possible (it could fail due to being read-only, for example).
Alternatively, one can delete the delta file outside of XM6.


The remaining menu items are global preferences: they can be set using
any of the drive menus. They are saved in XM6's configuration file.

 Default (Initial / Subsequent)

These menus allow you to pick the action to be selected by default when
an image is inserted. The "initial" setting is used when no delta file
exists, and the "subsequent" setting is used if an existing delta file
was successfully loaded upon insertion.

The choices are the same as above. The Delete action is not available as
a default setting - it can only be selected manually, for safety reasons.

The default setting for Initial (no delta file exists) is to keep any
changes without asking. If you switch it to Discard, delta files will
no longer be created unless you deliberately change the action to be
either Keep or Ask after an image has been inserted.

The default setting for Subsequent (a delta file already exists) is to
keep any changes without asking. Switching it to Discard is almost the
same as write-protecting every single delta file: no further changes
will be enacted unless you manually change the action after insertion.

 Enable Delta Files

This setting determines whether delta files are supported at all.
If disabled, delta files will not be loaded, created, or updated.
It is enabled by default.

Enabling this option while a disk is inserted will not necessarily
function as you might prefer in certain cases, due to safeguards.





 Additional Floppy Drives
------------------------------------------------------------------------

An X68000 contains two internal floppy disk drives, but it is possible
to add up to two more. This optional expansion is now supported in XM6,
albeit with some caveats. It's not highly useful for games, as very few
support extra drives, and even fewer support them in such a way that it
becomes more convenient to use them.

Given the above, this is treated as an advanced feature and as such the
interface is slightly more difficult to use than for the regular drives.
This feature is also implemented dynamically, i.e. drives are connected
and removed based on user actions rather than configuration settings.

There are no corresponding submenus in the main menu bar; the primary
interface for these drives is through the pop-up (right-click) menu.
Command-line arguments and drag-and-drop can also be used to insert
up to four files at once. Ctrl-Alt-E will eject all four drives.

The TIMER and POWER LED panes will be repurposed for the extra drives
whenever they are connected. Due to space limitations, the disk names
will not be displayed.

There is no Resume feature for the extra drives. It's not very useful
in this case and would require breaking state file compatibility.

For compatibility reasons, only two drives will be available by default.
To connect a third or fourth drive to the virtual machine, simply insert
a disk image into the respective drive. You may need to reboot the VM
in order for the system to recognize the new drives, but not always.

To disconnect the additional drives, eject their disks and reset XM6.
You could also quit XM6 or load a suitable state file.

State files record whether a drive has a disk image loaded but not the
drive connection state, which must therefore be inferred when a state
file is loaded: if there was a disk image in the drive when the state
was saved, that drive will be connected when the state is reloaded.

Connecting Drive 3 will automatically connect Drive 2, since it causes
problems with most software otherwise. Similarly, Drive 2 will remain
connected as long as Drive 3 is; it is permissible to disconnect Drive 3
while keeping Drive 2, however. Operating with only three drives is also
fully supported.





 Troubleshooting Emulation Issues
------------------------------------------------------------------------

If you are having issues with X68000 software, the following may help.
See also the following section for solutions to problems that may be
rooted in your particular hardware/software environment instead.


 Reset the VM

It is best to reset the virtual X68000 (or restart XM6) before switching
to a different game or program. It's easy: just press Alt-R.

Furthermore, certain configuration changes require a reset before they
will take effect. (How is the X68000 software supposed to know that you
just hot-swapped a MIDI board, for example?)

Reset and Clear may fix graphical glitches in a few games that don't properly
initialize RAM used for graphics; however, it also wipes out SRAM, which may
affect your settings. Most users don't have anything important in SRAM though.
Restarting XM6 is a safe alternative if you are unsure.


 Check the notes

There are items in the Help menu that allow you to download, update,
and view the integrated notes file, which is updated frequently and
includes helpful information on running various X68000 programs.
If these menu items are unavailable, consult the read-me file.

If you have floppy disks inserted, the best-guess name of the program
you are running will be copied to the clipboard, allowing you to easily
find the appropriate entry, if one exists.

The notes are sometimes updated as frequently as daily, depending on
activity levels of our preservation project.

This should be your first recourse.


 Try different input devices

If you can't start a game, it might require mouse or controller input.

This is more common for doujin and unprofessional software;
commercial-grade games almost always support the keyboard,
unless they are entirely mouse-driven.


 Update the emulator

This is as simple as selecting "Check for Updates" under the Help menu,
so it's a quick option to try before messing with the settings.

Accuracy of emulation does improve occasionally. If you submit a report
about problems you are having, they might even get fixed!

Be assured that your author's policy is to not remove features or alter
the interface in a way that might annoy people (without at least making
the change user-configurable). If you feel that this social contract has
been violated by a recent update, please express your dissatisfaction
through email.


 Refrain from using the cheating subsystem

XM6 cheats modify X68000 memory directly, which can cause problems,
even if they seem to be working, and even if you later turn them off.

Resetting the VM will disable cheats and put the VM into a known state.


 Email the author

This technically doesn't qualify as troubleshooting, but if you've
at least tried all of the above then your feedback is of interest
and may end up being used to improve the notes file or even XM6.


 Switch the write-protect state of floppy disks

Most games don't care either way, but some won't run correctly if a disk
is in the wrong state. Typically the disk will be ejected repeatedly
until you either set or clear the Write Protect flag in the drive menu.
You can also force the write-protect state by adding [R] or [W] to the
disk image file name.

Disks in the internal database will have their write-protect state
set automatically upon insertion, which is another reason you should
update the emulator regularly.


 Try different System Clock settings

Some programs are timing sensitive and may crash if the clock rate is
set too low. A higher clock rate usually isn't fatal, and sometimes
makes games run more smoothly, but may cause poorly programmed software
to run too fast. Many commercial games have a note in the documentation
instructing the user to run the game at a 10 MHz clock rate.

Although it is not recommended for general use, the no-wait-MPU setting
sometimes helps. It effectively(*) runs the emulated CPU as fast as your
computer is able, so it uses up a lot of resources. While it is active,
you will see an exclamation point (!) in the caption, unless you are
also debugging, in which case this setting doesn't apply.

* Technically this mode is not the same as emulating a CPU with a high
clock rate because VM events (interrupts, DMA, etc.) are paused while
the emulator burns up excess time. An adaptive clock rate would produce
more natural results but is difficult to regulate.


 Disable the Fast Floppy option

Obviously this only helps if you are running software from floppy disks.
It fixes graphical glitches in a few games. A tiny number of games will
fail to run if Fast Floppy is enabled. Because of this, Fast Floppy is
disabled by default. It's not really needed if you use fast-forward.


 Increase the amount of X68000 RAM

A tiny number of games need more than the default of 2 MB.
You may also need more RAM if running from a hard drive.

4 MB should be sufficient to run any game, but be warned that
the size of state files is proportional to the amount of RAM!

No X68000 game is known to make use of more than 9 MB of RAM.
Using the maximum 12 MB of RAM is unnecessary and wasteful.


 Disable MIDI

It's worth a try; MIDI emulation formerly caused problems with one game.
(There is also one poorly programmed freeware game that requires MIDI.)


 Reinitialize

File > Reset and Clear will wipe out all RAM including SRAM,
which contains several X68000 settings. SRAM can also contain
viruses, although modern versions of XM6 should be immune.

To reset everything, delete XM6.ini and SRAM.DAT while XM6 is
not running. They will be recreated the next time XM6 starts.
(Technically, they won't be written out until XM6 then exits.)

(This should be the last resort unless you know for sure that
you messed with the settings. On the other hand, most of the
defaults are well chosen, so you aren't likely to lose much.)

Note that most of the settings are also saved within state files,
so loading an old state file will also change the configuration.
One could create a state file immediately after reinitializing
in order to have a clean baseline. Another strategy is to set
XM6.ini to be read-only at the file system level. There is a
menu item under the Tools menu that will toggle the read-only
attribute on that particular file for you.


 Try the MBCS edition

In addition to lacking Unicode support, the MBCS edition of XM6
also omits certain improvements or features that could impact
compatibility. If the MBCS version appears to alleviate some
sort of difficulty, please notify the author via email.





 Troubleshooting Emulator Problems
------------------------------------------------------------------------

General emulator compatibility problems are documented in this section.
See above for troubleshooting problems with X68000 software.


 Unwanted video artifacts or graphical inconsistencies occur in some games

The Smoothing option often causes (and sometimes cures) graphical glitches.
(Smoothing is performed by video drivers, so this sort of problem could only
be universally solved with a replacement algorithm implemented in software.)
Smoothing is only applied when stretching non-integrally, so adjusting the
stretching settings to eliminate non-integral stretching may also correct
the problem. Note that you will be unable to toggle Smoothing at times
when anti-aliasing would not be applied; you can use this as a quick
way to check if stretching is integral or not. (A more daunting method
is to open the View > Win32 > Bitmap window and examine the bottom line.)

Another possibility is DPI virtualization. If your display scaling
is not set to 100% then the program window gets forcibly stretched,
which will cause distortion and sometimes glitches. This does not
occur on older systems (before NT 6). It may or may not occur on
newer systems: you can check the View > Win32 > OS Info window;
if it says "Per-Monitor v2" under "DPI Awareness" then you should
never have any problems, otherwise you may have to restart your
system under certain circumstances in order to get rid of the
fuzzy look or fix other problems in the GUI. I've done all I can.

(As an aside, external programs or OS components may show a different
level of "awareness", but they can only detect the process-default
setting. The OS Info window reports the actual per-thread setting.)

To help differentiate artifacts caused by the OS / drivers, you could use
Alt-PrtScr to copy the main window to the clipboard as a bitmap and then
compare it to a pre-driver screen shot made with Alt-Q or the Tools menu.

For other possible causes, see Troubleshooting Emulation Issues above.


 Previously configured MIDI devices sometimes revert to "(none)"

Some systems are picky about the entire audio path; an unplugged jack
can be enough to temporarily kill off software synths, causing XM6 to
see them as non-working. Another possibility is that you loaded a state
file that was made without MIDI configured or when there were more MIDI
devices available than at the present time.


 Previously configured settings have unexpectedly reverted

The most likely reason is that you loaded a state file made using
different settings.

Most of the program's settings are also saved within state files,
so loading a state file might end up changing your configuration. 
This has advantages and disadvantages. One benefit is that you
don't need to continuously adjust the settings for compatibility
with various X68000 software - once you've made adjustments for
a particular case, they will be preserved in any state files you
subsequently make such that you can easily return to them.

To avoid losing your current configuration, you could make a clean
state file with your preferred settings. In fact, you could make
several several state files geared for different circumstances.

Another strategy is to locate the text-based configuration file
(XM6.ini) and set it to be read-only at the file system level.
Thereafter, any configuration changes will be discarded on exit.
The Tools > Configuration File > Read-Only menu item will have
a check mark if the file is currently read-only. Selecting the
menu item will toggle the file's read-only attribute for you.


 The program is sometimes very slow to start

It may take a few extra seconds to start the first time (per session)
because the executable and DLLs are not yet in the system cache.
There may also be a delay the first time a compressed file loads,
because the 7-Zip DLL is only loaded when first needed.

If it takes more than a few seconds, the cause is almost always some
background "service" (disservice?) sucking up all the system resources.
This problem is depressingly common on modern PCs and has been for years.


 Inputs from your keyboard are sometimes not detected

I have found that XM6 will sometimes not receive very brief key
presses from a cheap wireless keyboard that I own. This never seems
to happen for wired keyboards or physical mice (wireless or not).
Increasing the input polling frequency does not mitigate the issue.





 Miscellaneous Caveats
------------------------------------------------------------------------

Modifying media of any kind of outside of XM6 can cause inconsistencies
if you are also loading state files because certain disk parameters may
be cached by software within the VM (such as Human OS). But few people
actually do this sort of thing. A more likely scenario is when a disk
gets written to in XM6 but you then load a state file made before the
modification occurred: the VM and the disk image could be out-of-sync.
If the active software then writes to the disk, false assumptions about
the contents of the virtual disk could lead to data loss or corruption.

If you know or suspect that a particular state file is out-of-sync with
removable media, ejecting and then reinserting the relevant images may
be sufficient to correct any problems. You may not even need to do this
with simpler software, such as many games. Resetting the virtual machine
will also clear up any inconsistencies, although this is tantamount to
abandoning the state file because a reset discards most of the state you
might be interested in. However, it is the second-safest* way to protect
your media, particularly hard disk images, which cannot be ejected.

* The safest way is to set the read-only attribute on all your images.
  Your OS will not allow XM6 to write to read-only files. It's what I do.
  Advanced users can refer to the section on delta files for more info.

While inserting the same disk image into multiple drives simultaneously
works and is supported (albeit physically impossible), write operations
on such a disk may not function as intended and are not recommended.

Inserting multiple disks sequentially into the same drive while emulation
is halted can cause confusion due to the way XM6 queues floppy images.
One should not assume that the UI is accurate in such cases.

The handler for directory-as-disk images is not Unicode compatible even
in the Unicode version. Such directories will work as long as the entire
path maps to the local code page for every component, however.

While recording audio (using the "WAV Dump" feature) an alternate method
of sound processing is used to ensure that the audio is recorded correctly
(except while fast-forwarding). As a result, you might hear the "live" audio
breaking up at times while recording is in progress, but the actual recorded
file will be unaffected. Now you can even pause the VM safely while recording.

Because the audio is no longer regulated while recording, the buffering
behaves unpredictably and may drift. Underflow will not corrupt the
recorded data, but if the internal buffer overflows, data will be lost.
(The buffer size is fixed and unrelated to the Sound Buffer in the options.)
In my environment, overflow only occurs if the sampling rate is 62.5 kHz
(which is the default) and it takes over 15 minutes for this to happen.
